Developer guide · Webhooks
Build a reliable outbound loyalty webhook consumer.
Use outbound webhooks to notify another system after a supported loyalty event. Keep commands in the correct API, verify every delivery, and design the receiver for duplicates and failure.
- Direction
- Reward Loyalty to receiver
- Delivery contract
- Signed, at-least-once
- Write path
- Agent or session API
Short answer
Use webhooks for facts, not commands.
Reward Loyalty supplies partner-scoped outbound webhooks for notification-only delivery after supported loyalty events. A webhook can tell a CRM, automation service, or data system what happened. It cannot award points, approve a redemption, or replace a write API. The developer builds and operates the public HTTPS receiver, verifies the signature, handles duplicates, and maps the event into the external system.
Decision criteria
Define the event boundary before the endpoint.
The producer, source transaction, identity, receiver, failure policy, and write path must agree before live events leave the application.
Committed fact
Choose the supported event that proves the business action has completed. Keep the POS, store, or other source transaction in its system of record.
Receiver identity
Map stable Reward Loyalty identifiers to the external record and decide which fields the receiver stores, hashes, or discards.
Recovery owner
Name who watches delivery history, repairs the receiver, reconciles missed work, and replays an external action when no product replay control exists.
Interface map
Give each interface one job.
A reliable design separates commands, signed-in product actions, event notification, and staff fallback.
Agent API
Use a scoped long-lived key for machine-to-machine reads and writes that current Agent API documentation supports.
Session-token REST API
Use the locale REST API when a signed-in member, staff, partner, or administrator performs the action through a custom client.
Outbound webhook
Receive a notification after a supported event commits. The receiver must not treat the notification as authority to perform another loyalty write without its own rule.
Brand and source control
White-label relevance: Supporting. Branding does not change the delivery contract. Source access permits extensions, while the buyer owns their design, security, tests, and update work.
Event contract
Map identity without rebuilding the ledger.
Consume the documented envelope and keep the event payload focused on the downstream task.
Subscription scope
An active endpoint receives only selected events available to that partner. Feature changes can affect new subscriptions, so review the maintained catalogue before setup.
Member identity
Use the stable member and card identifiers in the documented payload. Treat email or other personal data as optional input, not a durable join key.
Event lineage
Store the event ID, correlation ID, delivery ID, event name, and schema value needed for tracing. Do not assume delivery order across endpoints.
Privacy events
Treat deletion notices as best-effort signals and keep a separate privacy process that covers the external system, backups, logs, and failed deliveries.
Delivery model
Expect duplicates and visible failure states.
Outbound delivery is decoupled from the loyalty action so a slow receiver does not hold the sale or redemption open.
Dispatch
A pending delivery record is created after the event. Depending on installation configuration, work can run after the response or through the webhook queue.
Retry boundary
Timeouts and documented transient response classes can retry on the bounded delivery schedule. Permanent client errors, redirects, and exhausted attempts become terminal failures.
Duplicate requests
The contract is at-least-once. Deduplicate with the delivery ID before applying a downstream side effect, even when the same body and event ID return.
Paused endpoint
Repeated terminal production failures can pause an endpoint. Test deliveries do not reset or increase that production failure streak.
Production checks
Prove the receiver under failure.
A successful sample request proves reachability. It does not prove safe operation.
-
1
Expose one public HTTPS URL
Use a stable endpoint without embedded credentials, query strings, redirects, localhost, or private-network targets.
-
2
Verify before parsing
Read the exact raw body, verify the documented HMAC signature with a constant-time comparison, then decode and validate the event.
-
3
Acknowledge fast
Return a successful response after durable acceptance, then run slow CRM, automation, or reporting work in the receiver’s own queue.
-
4
Exercise recovery
Send a test, force a timeout and a permanent error, confirm delivery history, prove duplicate suppression, and alert on failed or paused delivery.
Product and operating limits
Keep notification and command paths separate.
- Outbound webhooks report supported events. They do not accept commands, create a universal connector, or guarantee delivery order.
- Delivery is at-least-once. The receiving system owns duplicate suppression and the safe retry of its own work.
- The event catalogue, payload fields, and feature access can change. Use the maintained event reference rather than a copied count or stale payload sample.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.