API reference

A connected system talks to IamBroker over HTTPS and receives events back as a signed webhook. Every route below authenticates with the X-Api-Key header issued when the system is provisioned, and is rate limited per system. An account is addressed by external_ref, an opaque reference chosen by the connected system.

Routes

Method	Path	What it does
POST	`/accounts/connect-init`	Starts the connection of a WhatsApp Business account. Returns the public identifiers the browser needs to open Meta Embedded Signup. No credential of ours crosses the wire.
POST	`/accounts/connect-callback`	Finishes the connection with the code Embedded Signup returned, together with the account and phone number identifiers. The access token is exchanged and stored encrypted.
GET	`/accounts/:external_ref/status`	Reports whether the account is connected, its phone number and its current messaging limit.
POST	`/contacts/opt-in`	Records that a contact agreed to be messaged: when it happened, where the consent came from and the wording agreed to.
POST	`/messages/send`	Sends a text or a template message on behalf of a connected account. An `Idempotency-Key` header replays the stored answer instead of sending twice.

Sending a message

POST /messages/send
X-Api-Key: your-api-key
Idempotency-Key: 5f2c0f1e-...

{
  "external_ref": "account-42",
  "to": "5511999990000",
  "type": "text",
  "content": { "body": "Your order shipped." }
}

The signed outbound webhook

IamBroker does not expose a queue. Every event leaves over HTTPS to the events URL registered for the connected system, signed with that system's own webhook secret. The signature travels in the x-broker-signature-256 header as the HMAC-SHA256 of the exact bytes of the body, prefixed with sha256=. Verify it against the raw bytes before parsing them. A delivery that fails is retried with exponential backoff and, after the last attempt, held in a dead-letter state.

POST https://your-system.example/events
x-broker-signature-256: sha256=<hmac of the exact body bytes>

{
  "event_id": "0f0a...",
  "event_type": "message.status_updated",
  "external_ref": "account-42",
  "occurred_at": "2026-09-07T12:00:00.000Z",
  "data": { "status": "delivered" }
}

Events

message.received: A customer wrote to the connected number.
message.status_updated: A message we sent moved to sent, delivered, read or failed.
account.connected: An account finished Embedded Signup and is ready to message.
account.disconnected: The account can no longer be used, for example after Meta revoked its access.
account.quality_degraded: Meta reported a drop in the quality of the connected number.

Credentials

The API key and the webhook secret are shown once, when the system is provisioned, and are never shown again by us or published anywhere. No key, secret or access token appears on this site.