Stripe
Webhook delivery
How Verlix verifies a delivery, what it answers, and what happens when something is off.
Stripe posts each event to a URL that belongs to one connection. Verlix decides what to do with the request in a fixed order: identify the connection, check the signature, check the account, store the event, then reply.
The delivery URL is a credential
The URL identifies your tenant, so anyone who has it can send requests to your connection. It is never written to logs. Do not paste it into tickets or chat.
Signature check#
Verlix reads the Stripe-Signature header, which has this shape:
Stripe-Signature: t=<unix timestamp>,v1=<hex digest>- The digest is an HMAC-SHA256 over the timestamp, a full stop, and the raw request body.
- Several
v1values may be present. The delivery passes if any one matches. - The header must contain exactly one
t. Anything else is rejected. - The timestamp must be within five minutes of Verlix's clock. An older one fails, which blocks replayed requests.
- Both the current and the previous signing secret are accepted, so a rotation does not drop deliveries mid-change.
What Stripe receives#
| Status | When | What Verlix does |
|---|---|---|
200 | The event is stored | Replies only after storage succeeded. Body reports how many events were stored and how many were set aside |
202 | The delivery cannot be trusted or placed: a bad signature, an unknown connection, or an account mismatch | Keeps the raw bytes for review and replies with an identical body every time, so the response reveals nothing |
429 | Verlix is under load for this tenant or source | Refuses, and asks Stripe to retry later using Retry-After |
404 | The source name in the URL is not registered | Stores nothing |
A 202 is deliberately not an error. Stripe treats it as delivered and will not retry, so a delivery answered 202 is one you should look into yourself. See Troubleshooting.
Retries#
Verlix answers 200 only after the event is stored, so a 200 always means the event is safe. If storing fails, Stripe gets an error status and redelivers on its own retry schedule. Verlix adds no retry queue of its own for webhooks.
Endpoint upkeep#
For connections that use webhooks, Verlix looks at the endpoints on your Stripe account about every 30 minutes. A missing endpoint is created, and a disabled one is enabled again. If Stripe cannot be listed at that moment, Verlix does not assume the endpoint is gone.
Signing secrets are stored, not fetched
The secret Stripe generates for the endpoint is stored encrypted. If you rotate it in Stripe, tell Verlix, because a rotation is not detected on its own. Until it is updated, new deliveries fail the signature check and are set aside.