Webhooks
When an event occurs, we send you a webhook notification to tell you what happened so you can take action and keep your business running smoothly.
Webhooks provide definitive confirmation of a status update and are used for a variety of purposes, such as notifying a member onboarding, notifying new transactions in your programme, and notifying a change in the status of a member's bank connection.
When the event you subscribed to by registering a webhook occurs, we POST the data to the URL you provided, in the JSON format documented on each event's page below.
You can authenticate Spaycial as the author of a webhook request using a signature system - see Verifying webhook signatures.
Registration and management
Manage your webhook subscriptions with Register a webhook, Update a webhook, Delete a webhook and List webhooks.
Delivery starts at subscription
Webhooks are not retroactive. We send an event only for changes that happen after your webhook is registered: members created, transactions enriched or claims resolved before that moment are not replayed, and nothing that happened earlier is sent when you subscribe.
To load what already exists, read it with the API instead, for example List webhooks shows your subscriptions, and the member and transaction endpoints return the data recorded so far. Register your webhook before you open the programme to members, so that no event is missed.
Retries
When we make a POST call to your webhook URL, we check the response and schedule a retry if it has an error status. For example, if your server returns a 500 response, the call is retried until you return 200.
We try a maximum of 6 times, including the first call, following this schedule: 10 minutes, 1 hour, 24 hours, 48 hours, and 72 hours after the previous attempt. After the 6th attempt, we stop retrying and the data is lost.
Every call carries an AttemptNumber header, starting at 0, identifying how many retries preceded it.
Test calls
You can test some of these webhooks with a dedicated call: Send a test customer transactions webhook and Send a test bank connections update (v2) webhook.
Which events apply to your integration
The Importance column tells you what to build first. Must have events carry data your integration cannot do without; Nice to have events improve the experience but can wait. Importance is independent from your integration profile: a must-have event can still be marked "Not needed" for your profile, for example receipt_updated when receipt scanning is disabled.
| Event | Importance | Mall | Non-mall | No scan | Init via web app | Own offers | Stores in platform |
|---|---|---|---|---|---|---|---|
customer_creation | Nice to have | ||||||
customer_subscription | Must have | ||||||
customer_transactions | Must have | Not needed | |||||
all_transactions | Must have | Not needed | |||||
receipt_updated | Must have | Not needed | |||||
bank_connections_update_v2 | Must have | ||||||
bank_association_notification | Nice to have | ||||||
bank_status_update | Nice to have | ||||||
claim_update | Must have | ||||||
store_list_updated | Nice to have | Not needed | |||||
initial_transaction_update | Nice to have | Not needed | |||||
offer_updated | Nice to have | Not needed | |||||
reward_updated | Must have | Not needed |