Webhook endpoints
A webhook endpoint is a URL on your server that receives a signed POST for each event it subscribes to. You manage endpoints under Developer → Webhooks.
Endpoints belong to one environment. A sandbox endpoint receives only sandbox events, and a live endpoint receives only live events, each with its own signing secret. Each environment can have up to five endpoints. Switch environments to manage the other side. See Environments.
Owners and developers can add, edit, ping and delete endpoints in both environments. Viewers can read them. In live, changing an endpoint asks you to confirm it's you. An emailed code works here. See Two-factor and step-up.
URL rules
The endpoint URL must be a public https:// address. Stridge refuses:
http://URLslocalhostand*.localhost- private or internal IP addresses
To receive webhooks on your own machine while you build, use a public https tunnel to it.
The same rules apply every time you edit an endpoint, so an older endpoint with an http:// URL keeps receiving deliveries, but you need to move it to https before you can change it. At delivery time, Stridge also refuses a host that resolves to a private address and follows at most three redirects.
Add an endpoint
Switch to the environment the endpoint is for, then choose Developer → Webhooks → Create endpoint.
- Name: a label your team recognises.
- Endpoint URL: a public https URL that responds
2xxto signedPOSTrequests. - Subscribed events: the event types to deliver. Only the selected types reach this endpoint. See Events list.
The dialog shows the Signing secret. Choose Copy secret and store it on your server. It is shown only once and can't be retrieved later. When you have it, choose I've copied my secret.
Your server uses the signing secret to check that each delivery came from Stridge. Every delivery carries webhook-id, webhook-timestamp and webhook-signature headers. See Verify signature.
If you lose a signing secret, it can't be shown again. Delete the endpoint and create a new one.
Test an endpoint with a ping
A ping checks that your server is reachable and verifies signatures.
- On the endpoint's row, open Endpoint actions and choose Send a ping.
- Choose Send ping.
Stridge sends one signed webhook_endpoint.ping event to that endpoint only, even if the endpoint is disabled or doesn't subscribe to it. A ping carries no data and is never retried.
To see real events arrive, simulate a deposit in the sandbox. Its events go to every sandbox endpoint that subscribes to them.
Edit, disable or delete an endpoint
- Edit: select the endpoint to open its details, then choose Edit endpoint. You can change its name, URL, subscribed events and Active state, then choose Save changes.
- Disable or enable: open Endpoint actions and choose Disable endpoint or Enable endpoint. A disabled endpoint receives nothing until you enable it again.
- Delete: open the endpoint's details and choose Delete, then Delete endpoint. Deliveries stop at once, and this can't be undone.
Event history and resends
The Event history tab lists every event in this environment with its status: Pending, Processing, Completed or Failed. Select an event to see its payload and every delivery attempt, with the request headers, response and timing.
To deliver an event again, open it and choose Resend, pick an Endpoint, and choose Resend event. A resend is one extra attempt. It doesn't change the automatic retries or the event's status. Events older than 30 days can't be resent.
Retries
When a delivery fails, Stridge retries it automatically:
| Environment | Retries |
|---|---|
| Live | Up to 6 retries, with a backoff that starts at 10 seconds and doubles each time |
| Sandbox | Up to 3 retries, with the same backoff |
An event that fails every retry is marked Failed. To catch up on events your server missed, see Get missed events.
What a delivery contains
Each delivery's body says which environment it came from: livemode is true in live and false in the sandbox, and environment_id names the environment. Sandbox deliveries also carry reset_epoch, which goes up each time the sandbox is reset. See Server setup.