Webhooks are notifications of events that occur in the Shuttle system.
Webhook Destinations
Webhook targets are set at two levels:
| Level | Field | Scope |
|---|---|---|
| Application | webhook_target on the application | Default destination for every instance in the application |
| Instance | webhook_target on the instance | That instance only |
An instance target replaces the application target — events are not sent to both. Where an instance has its own webhook_target, events for that instance are delivered only to the instance target, and the application destination receives nothing for that instance. Instances with no webhook_target of their own fall back to the application destination.
To deliver an instance's events to both, set the instance webhook_target to a fan-out target listing both URLs — see Webhook Configuration.
Handling Webhooks
- Webhooks are sent to a HTTPS endpoint on your server
- Webhook body is a JSON object
- The endpoint must return a 2xx status code. Any other status is treated as a failure.
- Each webhook contains a
keyfield that you can use to deduplicate webhooks. The same event sent to multiple URLs will have a uniquekeyfor each URL. - Webhooks will typically arrive within a few seconds of the event. Delivery timing is not guaranteed — if the user is waiting on a result, poll the API every 2-3 seconds rather than relying on webhook timing.
- Webhooks may arrive out of order.
- If you run batches of payments, ensure your endpoint can handle high volumes of simultaneous events.
Webhook Security
- Webhooks do not contain any sensitive information, just object references. Fetch the full object via the API using your credentials.
- Webhooks must target a HTTPS endpoint on port 443.
- All webhooks originate from one of the following IP addresses:
- 52.51.86.26
- 54.229.12.118
- 54.76.31.104
- 34.252.246.134
Webhook Retry Policy
By default, webhooks are not retried. A response of HTTP 200 or HTTP 204 is considered successful; any other status is a failure.
To activate retries, configure a retry policy in the webhook target URL. When retries are configured, each attempt occurs approximately 1 minute after the previous failure.
Note: Retries are disabled in the sandbox environment.
Webhook Configuration
Webhook targets are stored as a URL string. The string supports a simple syntax for configuring retries, failover, and multiple destinations. See the webhook_target field on the instance or the attach webhook endpoint.
Operators
| Operator | Description |
|---|---|
|N | Retry up to N times, with approximately 1 minute between each attempt |
> | Failover: if the current URL fails, try the next |
, | Fan-out: deliver to multiple destinations simultaneously |
Examples
https://targetA/url: send to targetA, no retrieshttps://targetA/url|2: send to targetA, retry once on failurehttps://targetA/url|120: retry every minute for up to 2 hourshttps://targetA/url>https://targetB/url: send to targetA; on failure, try targetBhttps://targetA/url>https://targetB/url>https://targetC/url: targetA, then targetB, then targetChttps://targetA/url|60>https://targetB/url|5: retry targetA for up to 1 hour, then fail over to targetB for up to 5 minuteshttps://targetA/url,https://targetB/url: send to both targetA and targetBhttps://targetA/url|60,https://targetB/url|60: send to both, each with up to 1 hour of retries