Webhooks overview

Webhooks tell your systems, in near real time, when important data changes inside Spendstream. Instead of polling the API repeatedly, you register a URL and Spendstream sends an HTTP request to it whenever a relevant event occurs.

Supported events

Two events are sent today.

⚠️ Warning: No other event types are sent. Brand and promotion changes are not delivered by webhook, so keep your catalogue current by calling getBrands, getCategories and getPromotionsList on a schedule.

How delivery works

1. Something changes in Spendstream, for example a customer completes a gift card payment or an affiliate network confirms a sale.
2. Spendstream builds a signature, then sends a form-encoded POST to every webhook URL registered for your publisher account.
3. Your endpoint verifies the signature, records the change and responds with a 2xx status.

 
sequenceDiagram
    participant SS as Spendstream
    participant EP as Your endpoint
    participant Q as Your queue
    SS->>SS: Build Signature
    SS->>EP: POST with Signature and TimeStamp headers
    EP->>EP: Verify signature and timestamp
    EP->>Q: Store event for processing
    EP-->>SS: 200 OK
    Q->>Q: Upsert the record

Registering your webhook URL

Registration is manual. Give Spendstream the HTTPS URL of your endpoint for each environment, and Spendstream will register it against your publisher account. There is no self-service registration endpoint.

💡 Tip: Use a different URL for staging and production. The signature includes your exact URL, so a staging delivery can never be replayed as a valid production delivery.

What you must know before you build

Next steps

• Read Webhook security and implement signature verification.
• Read Webhook processing best practices to make your handler safe to run repeatedly.
• Test end to end using Webhook testing.