Webhooks

Rather than polling GET /v1/api/orders/{id} or /mailboxes/status in a loop, register a webhook URL and Infrabox will POST to it as domains and mailboxes change status.

Set your webhook URL

Webhook URL is configured per-team (/v1/api/account/webhook) or per-workspace (/v1/api/workspaces/webhook) — a workspace-level URL, when set, is used for that workspace’s events instead of the team-level default.

curl -X PUT https://api.infrabox.software/v1/api/account/webhook \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-app.com/webhooks/infrabox" }'

Pass null for webhook_url to remove it.

Delivery

Each event delivers as a POST with a JSON body carrying at least:

{
  "event": "mailbox.status_changed",
  "entity_type": "mailbox",
  "entity_uid": "mb_123456789",
  "payload": { "...": "entity-specific fields" }
}

entity_type is domain or mailbox. Delivery is retried on failure (non-2xx response, or your endpoint timing out) with backoff — respond 2xx quickly and do slow processing asynchronously on your side rather than inside the request.

When you don’t need webhooks

For short-lived operations you’re actively waiting on — a single order or sequencer export — polling the corresponding status endpoint every few seconds is simpler and fine. Reach for webhooks when you’re driving provisioning at volume and don’t want to hold a poll loop open per job.