Webhooks: Receiving Payment Events in Your System
Webhooks let Stream notify your server the moment something happens — a payment succeeds, an invoice completes, a subscription renews. They are the reliable way to confirm money movement. Redirect parameters are not.
Behaviour is identical in sandbox and production.
Setting one up
Go to Settings → Webhooks in your dashboard and choose Create Webhook. You give the webhook a name, the URL on your server that should receive the events, and a secret key, then pick the events you want to be notified about. Treat that secret like a password — it must never appear in browser or mobile code.
What Stream sends
{
"webhook_delivery_id": "uuid",
"event_type": "PAYMENT_SUCCEEDED",
"entity_type": "PAYMENT",
"entity_id": "uuid",
"entity_url": "https://stream-app-service.streampay.sa/api/v2/payments/{id}",
"status": "SUCCEEDED",
"data": { ... },
"timestamp": "2025-07-15T14:41:21.705Z"
}data carries the payment, invoice, customer_id, metadata, payment_link and subscription, each null when it does not apply. timestamp is the event time in UTC, written without an offset.
Matching events to your own records
data.metadata is the custom_metadata you set when creating the payment link, or {}. It is set once at link creation and cannot be changed afterwards, so every webhook for that link — including all its subscription renewals — carries the same value. Use data.invoice.id or data.payment.id to tell one renewal cycle from another.
Subscriptions created directly through the API rather than through a payment link have no custom metadata: those webhooks arrive with metadata: {} and payment_link: null. They do carry customer_id, so fetch GET /api/v2/consumers/{id} if you need your own reference.
Headers
-
X-Webhook-Event,X-Webhook-Entity-Type,X-Webhook-Entity-ID X-Webhook-Timestamp-
X-Webhook-Signature—t=<unix seconds>,v1=<hex signature> User-Agent: StreamApp-Webhook/1.0
Verify the signature
Build the string "{t}.{raw_request_body}" from the raw body bytes exactly as received, compute HMAC-SHA256 with the webhook's secret, hex-encode it, and compare against v1 with a constant-time comparison. If you parse the JSON and re-serialise it before hashing, the signature will not match.
Use a timestamp tolerance of ±5 minutes against your server's UTC clock. Every attempt is signed fresh with a new timestamp — automatic retries and manual replays alike — so a retry arriving hours later still passes that check. The body itself never changes between attempts.
import hmac, hashlib
def verify(secret, raw_body, header):
parts = dict(p.split("=", 1) for p in header.split(","))
msg = f"{parts['t']}.{raw_body.decode()}"
expected = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])What counts as delivered, and what gets retried
- Success: any 2xx response within 15 seconds. Return 2xx as soon as you have verified the signature, and do the heavy processing afterwards.
- Retried: 5xx, timeouts, connection errors, 408 and 429.
- Not retried: every other 4xx, including 409 and 422 — and 3xx redirects. Your webhook URL must be the final destination, not a redirect.
The schedule is a few quick attempts, then roughly 5 minutes, 30 minutes, 2 hours and 6 hours. If a delivery has not succeeded within about 8.5 hours it is marked FAILED. It can still be resent manually after that.
If your endpoint keeps failing, the webhook is switched off
After several consecutive delivery failures Stream automatically disables the webhook, and sends you a notification when it does. This is protective behaviour, not a fault.
To recover: confirm your endpoint is reachable and responding correctly, then retry a delivery. The webhook reactivates once a delivery succeeds.
Resending and inspecting deliveries
You can replay any delivery from the Webhooks management page in the dashboard, or through the API with POST /api/v2/webhook-deliveries/{webhook_delivery_id}. A resend sends the original stored payload unchanged, including its metadata and body timestamp; only the signature and timestamp headers differ.
GET /api/v2/webhook-deliveries/{id} returns the full record: the exact payload sent, status (PENDING, DELIVERED, RETRYING, MANUAL_RETRYING, FAILED, CANCELLED), retry_count, attempt_count, next_retry_at, delivered_at, and the latest attempt's response code, body, headers and error.
There is no "send test webhook" button. To test, trigger a real event in sandbox — for example a failed payment using a decline test card.
Deduplicate on webhook_delivery_id
Order is not guaranteed and duplicates do occur, so your handler must be safe to run twice. Check current state before acting.
Deduplicate on webhook_delivery_id, a top-level field in the body. It stays the same across retries and resends of the same delivery, while a genuinely new event gets a new one.
Do not deduplicate on entity_id + event_type. Some events legitimately repeat for the same entity — PAYMENT_PARTIALLY_REFUNDED on every partial refund, INVOICE_UPDATED on every update, and renewal events every cycle — and you would silently drop real events.
Events you can subscribe to
Payments
PAYMENT_SUCCEEDED, PAYMENT_FAILED, PAYMENT_CANCELED, PAYMENT_PARTIALLY_REFUNDED, PAYMENT_REFUNDED, PAYMENT_MARKED_AS_PAID
Invoices
INVOICE_CREATED, INVOICE_SENT, INVOICE_ACCEPTED, INVOICE_REJECTED, INVOICE_COMPLETED, INVOICE_CANCELED, INVOICE_UPDATED
Subscriptions
SUBSCRIPTION_CREATED, SUBSCRIPTION_ACTIVATED, SUBSCRIPTION_INACTIVATED, SUBSCRIPTION_CANCELED, SUBSCRIPTION_FROZEN, SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY, SUBSCRIPTION_CYCLE_RENEWAL_FAILED, and the plan-change family.
Payment links
PAYMENT_LINK_PAY_ATTEMPT_FAILED is the only payment-link event. There is no event when a link is deactivated, expires or completes.
Which event fires when something fails
-
A failed payment-link attempt sends only
PAYMENT_LINK_PAY_ATTEMPT_FAILED. A link creates the invoice and payment only after success, so there is no payment record to fail andPAYMENT_FAILEDis not sent. -
A failed subscription renewal sends both
PAYMENT_FAILEDandSUBSCRIPTION_CYCLE_RENEWAL_FAILED. Match onPAYMENT_FAILED— it carries the full linking data, while the renewal event carries only{"payment_id": ...}.
Installments and renewals
- Each installment paid emits its own
PAYMENT_SUCCEEDED.INVOICE_COMPLETEDfires only once every installment is paid. - A successful renewal produces
INVOICE_CREATED→PAYMENT_SUCCEEDED→INVOICE_COMPLETED, plusSUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY.
One duplicate case to handle
max_number_of_payments: 1 is checked when the checkout page opens, not when payment completes. If two checkout pages are opened before the first payment finishes — two customers, or one customer in two tabs — both can be paid. It is rare, but worth handling.
Detect it as a second PAYMENT_SUCCEEDED with the same data.payment_link.id but a different data.invoice.id, and refund the extra payment with POST /api/v2/payments/{id}/refund.