Skip to main content
Surge sends an HTTP POST to a URL you configure whenever something happens in your project: a message arrives, a contact opts out, a campaign is approved. You register one endpoint URL per project and filter by type in your handler.

​
Where to configure your endpoint

Webhook endpoints are configured at the project level in the dashboard, under the top-level Webhooks page. A project-level endpoint receives events from all accounts under that project.

​
Event taxonomy

Surge can send the following events to your webhook endpoint depending on the subscriptions you configure:

​
Envelope shape

Every webhook payload has the same outer envelope:
The data object varies by event type. See the individual event pages for their payload shapes.

​
Retries and timeouts

  • Surge expects a 2xx response 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 200 quickly; 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 our SDKs, see Receiving Messages & Webhooks.