Webhooks Overview
Surge sends an HTTP POST to a URL you configure whenever something happens on your platform: a message arrives, a contact opts out, a campaign is approved. You register one endpoint URL per platform and filter by type in your handler.
Where to configure your endpoint
Webhook endpoints are configured at the platform level in the dashboard: Settings → Webhooks. A platform-level endpoint receives events from all accounts under that platform.
Event taxonomy
Surge fires 13 event types across six categories:
| Category | Events |
|---|---|
| Message | message.sent, message.delivered, message.failed, message.received |
| Contact | contact.opted_in, contact.opted_out |
| Conversation | conversation.created |
| Campaign | campaign.approved |
| Phone number | phone_number.attached_to_campaign |
| Link | link.followed |
| Voice (flag-gated) | call.ended, recording.completed, voicemail.received |
Voice events require the feature flag to be enabled on your platform. Contact support to have them turned on.
Envelope shape
Every webhook payload has the same outer envelope:
{
"id": "evt_01jav96823f9x9054d6gyzpp16",
"type": "message.received",
"timestamp": "2024-10-21T23:29:43Z",
"account_id": "acct_01jrz...",
"data": { ... }
}The data object varies by event type. See the individual event pages for their payload shapes.
Retries and timeouts
- Surge expects a
2xxresponse within the request timeout. If your endpoint doesn't respond in time or returns a non-2xx status, Surge retries with exponential back-off. - Your handler should be idempotent. Surge may deliver the same event more than once.
- Return
200quickly; enqueue work for slow processing.
Signature verification
Every request includes Standard Webhooks signature headers. You should verify the signature before processing the payload. See Signature Verification for the full details and per-language examples.
Setting up a handler
For a walkthrough of configuring your endpoint, verifying signatures, and handling events in Python, TypeScript, Ruby, and Elixir, see Receiving Messages & Webhooks.