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:- Set up a publicly accessible HTTPS endpoint on your server
- Register your webhook URL in the Surge dashboard
- 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 a200 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:- Make your webhook handlers idempotent - receiving the same webhook multiple times should not have any unintended side effects
- Validate webhook signatures to ensure the events you receive are coming from Surge.
- Respond to webhooks quickly - if your server is slow to respond, we may attempt to deliver the webhook multiple times