Webhook testing
Test your webhook receiver on staging before go-live. Read Webhook security and Webhook processing best practices first.
Setting up
- Give Spendstream your staging webhook URL. Registration is manual.
- Use a publicly reachable HTTPS URL. A tunnelling tool can expose a local server during development.
- Confirm the URL you give Spendstream is the exact value your code uses in the signature check.
Trigger a real delivery
The simplest way to get a real event is to perform an action on staging.
Event | How to trigger it |
| Call |
| Complete a gift card purchase using the steps and test cards in Testing payments on staging: full walkthrough. |
Save the first raw request you receive. Use it to confirm the exact fields inside the transaction or user JSON string, because the examples in this documentation are illustrative.
Test scenarios
Scenario | How to test | Expected result |
Signature verification | Send your endpoint a request with a wrong |
|
Stale timestamp | Replay a captured request after your allowed window. |
|
Wrong URL | Change the URL constant in your code. | Verification fails, showing the URL is part of the signature. |
Duplicate events | Replay the same captured request twice. | Data is unchanged the second time. |
Out-of-order events | Deliver an older state after a newer one. | Your handler ends with the latest state, for example by fetching |
Retry handling | Stop your endpoint, trigger an event, then restart. | No event arrives, because there is no retry. Your reconciliation job recovers it from |
Failed internal processing | Force an error after acknowledging. | The payload is written to your failure log for replay. |
Upsert behaviour | Send an update for a record you do not yet hold. | The record is created. |
Fast response | Add a slow step to your handler. | Acknowledgement still returns quickly, with work done afterwards. |
⚠️ Warning: The signature does not cover the request body, so a captured request can be replayed with a different body inside the timestamp window. Your handler should confirm important values through the API rather than trusting the body alone.
Checklist
- [ ] My staging URL is registered with Spendstream.
- [ ] I captured real
TRANSACTION_UPDATEDandUSER_UPDATEDrequests. - [ ] Invalid signatures and stale timestamps are rejected.
- [ ] Valid requests return
2xxquickly. - [ ] Duplicate and out-of-order events are safe.
- [ ] My reconciliation job recovers a missed event.
- [ ] Failed processing is recorded for replay.
- [ ] No secret or login token appears in my logs.
On this page
- Webhook testing