Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Webhooks

Webhooks notify you in real time when messages are sent or received and when an inbound FaceTime Audio call rings, is answered, or ends. Configure webhooks from within the Project Blue dashboard alongside your API keys.

On this page

Configuration

In the Project Blue app, you can:

  • Paste the webhook URL you want to receive events at
  • Choose which events the webhook receives: inbound messages, outbound messages, inbound FaceTime calls
  • Send test payloads to verify your endpoint is working
Sample message and FaceTime call payloads on the API Webhooks tab.
Choose which events the webhook receives when you add it.

Delivery

Your endpoint should answer 2xx. Anything else — including a network error or a timeout — counts as a failure.

There are no retries. Each event is delivered exactly once; a failed delivery is not queued or replayed, so a webhook is not a durable log. Reconcile with /get-messages-api if you need guaranteed coverage.

After 20 consecutive failures the webhook is automatically disabled. The counter resets on the first success. Today that happens silently — there is no email and no dashboard banner, so check the Webhooks tab if events stop arriving.

Webhook payload

Message payloads include an additive event key, message.inbound or message.outbound. No other message fields changed. The direction field still indicates whether the message was inbound or outbound. Call payloads are documented at Inbound FaceTime calls.

event"message.inbound" | "message.outbound"Required
Additive key on message webhooks. Call events use facetime.inbound.ringing, facetime.inbound.answered, or facetime.inbound.ended and are documented under Inbound FaceTime calls.
messagestringRequired
The text content of the message.
destinationstringRequired
The phone number the message was sent to, in E.164 format.
receivedAtstringRequired
ISO 8601 timestamp of when the message was received.
directionstringRequired
Either "inbound" or "outbound", based on message direction.
messageIdnumberRequired
Unique numeric identifier for the message.
guidstringRequired
Globally unique message identifier.
linePhoneNumberstringRequired
The Project Blue line phone number associated with this message.
HubSpot accounts receive a wider payload
On accounts whose webhooks are configured through the HubSpot variant of the Webhooks tab, every field above is still present, plus contactPhoneNumber, dateReceived (a legacy alias for receivedAt), hubspotContactId (number), and hubspotContactIdText (the same id as a string). Those webhooks have no inbound/outbound toggles and are not covered by the auto-disable behaviour described above.
Guides