Webhooks are like having a super-responsive assistant who taps you on the shoulder whenever something interesting happens in your SMS operations. Instead of constantly asking “Did I get a message? Did someone click my link?”, webhooks proactively notify your application when these events occur.

​
Why use webhooks?

  • Real-time updates: receive instant notifications when things happen
  • Automation friendly: perfect for building automated workflows
  • Efficient: no need to poll for updates, we’ll let you know when something happens
  • Reliable: make sure you never miss an important event

​
Getting started

To start receiving webhooks, you’ll need to:

  1. Set up a publicly accessible HTTPS endpoint on your server
  2. Register your webhook URL in the Surge dashboard
  3. Implement handlers for the events you care about
While it’s not required to get started, we strongly encourage validating webhook signatures to ensure the events you receive are coming from Surge.

​
Webhook delivery & retries

When your server receives a webhook, it’s like getting a high-five from our system - and we want to make sure that high-five connects! Your endpoint should respond with either a 200 OK or 201 Created HTTP status code to let us know you’ve successfully received the webhook.

If your server is having a rough day (hey, it happens to the best of us!), our retry system has got your back: Surge will attempt to deliver the webhook up to 20 times, using exponential backoff with jitter to make sure we don’t overwhelm your system.

​
Best practices

To ensure you’re handling Surge’s webhooks like a pro:

  1. Make your webhook handlers idempotent - receiving the same webhook multiple times should not have any unintended side effects
  2. Validate webhook signatures to ensure the events you receive are coming from Surge.
  3. Respond to webhooks quickly - if your server is slow to respond, we may attempt to deliver the webhook multiple times

And as always, if you have any questions or need help, please reach out to us at support@surgemsg.com.

​
Webhook signature validation

Signatures provide a method to verify the authenticity and integrity of incoming webhooks. By using a shared secret and a defined verification process, you can ensure that webhooks are genuinely from Surge and haven’t been modified.

​
Surge-Signature header

Each webhook Surge delivers includes a “Surge-Signature” header that looks like this:

Surge-Signature: t=1737830031,v1=41f947e88a483327c878d6c08b27b22fbe7c9ea5608b035707c6667d1df866dd

Parameters:

  • t: Unix timestamp indicating when webhook was sent
  • v1: Lowercase hex-encoded HMAC-SHA256 signature
    • We may send more than one v1 hash when rolling credentials

Parameter names and values will not include , or =, so these can be split upon to parse the header.

​
Validation Steps

  1. Check timestamp: Verify timestamp is within an acceptable time window (such as 5 minutes) to prevent replay attacks.

  2. Generate payload: The payload signed to create the header is a concatenation of 3 things:

    1. Timestamp from step 1
    2. Period (.)
    3. Raw webhook body

    Example

    1737830031.{"type":"message.received","id":"evt_01jjfeev3hf9n9c7k5231hd3hr",...}

  3. Compute expected hash: Generate HMAC-SHA256 hash for the payload from step 2.

    • Use the signing secret you received when setting up your webhook endpoint.

  4. Compare hashes: Check computed hash from step 3 with v1 from header.

    • Use constant-time string comparison to protect against timing attacks.
    • There may be multiple v1 parameters in the header
      • Only compare to v1, not other versions which may be added in the future
      • If any of the v1 hashes match, the signature should be accepted as authentic