Webhooks overview Live

Webhooks move events between systems. We receive webhooks from your email provider and your SIP carrier so customer emails and phone calls land in the unified inbox. We also send outgoing webhooks to your URL so your downstream systems can react to message.com events.

Inbound webhooks (we receive)

Three inbound endpoints are live in production. Each is HMAC-signed; see Signature verification for the verification details.

POST /api/v1/email/inbound           , Your email provider delivers customer emails as tickets
POST /api/v1/email/outbound-webhook  , Delivery events (bounce/complaint/delivered) post back
POST /api/v1/webhooks/calls/inbound  , Your SIP carrier delivers call lifecycle events

• Email inbound, your ESP or our hosted SMTP delivers customer emails. We create tickets.
• Email outbound, your email provider posts delivery events back. We update message delivery status and suppression lists.
• Calls inbound, your SIP carrier posts call lifecycle events. We render the call in the agent inbox in real time.

Outgoing webhooks (we send)

Configure outgoing webhooks in the dashboard at /settings/integrations/webhooks. Pick the event types you care about and paste your endpoint URL. We sign every delivery and retry with exponential backoff.

// Configure at: Settings → Integrations → Webhooks
// Pick events you care about, paste your URL, save.

{
  "id": "evt_2026_05_13_abc",
  "type": "conversation.created" | "message.received" | "ticket.solved" | "call.ended" | ...,
  "createdAt": "2026-05-13T15:30:00Z",
  "workspaceId": "uuid",
  "data": { /* event-specific shape */ }
}

See Retries and idempotency for the retry schedule, idempotency keys, and dedupe rules.

Security model

Three guarantees apply across both inbound and outgoing webhooks:

1. HMAC signatures. Every payload carries a signature header. Verify it on receive (your side for outgoing, our side for inbound). Without verification, anyone who knows your URL can post fake events.
2. Replay protection. Signatures include a timestamp. Requests older than 5 minutes are rejected. Repeated delivery of the same id within a 24-hour window is idempotent.
3. HTTPS only. We refuse to deliver outgoing webhooks to http:// URLs. Inbound endpoints terminate TLS on our edge.

Full details at Signature verification.

Testing locally

To receive inbound webhooks in local development, tunnel a public URL to localhost with ngrok or a similar tool. For our inbound endpoints (where we are the receiver), you can simulate deliveries with a curl test against staging. For outgoing webhooks (where you are the receiver), point us at your ngrok URL from the dashboard.

Step-by-step in Test webhooks locally with ngrok.

Retries

If your endpoint responds non-2xx (or times out after 10 seconds), we retry with exponential backoff: 1m, 5m, 30m, 2h, 6h, 24h. After 24 hours of failures we mark the delivery dead and surface a warning on the dashboard. We do not retry past 24h to avoid clogging your system after a long outage.

Details and dedupe semantics at Retries and idempotency.

Common pitfalls

• Skipping signature verification. A webhook endpoint without HMAC verification is a public write API. Always verify.
• Slow handlers. Anything over 10 seconds is a timeout. Queue work asynchronously and ack with 200 fast.
• Treating retries as duplicate events. They are the same event redelivered. Dedupe by the id field, not by content.
• Hard-coding the secret in source. Webhook secrets belong in environment variables or a secret manager. Rotating them when they leak is a breaking change for live integrations.