Introduction
What is a Webhook?
A webhook is a simple event-notification system. When an event occurs in Reward Gateway, a payload of JSON data containing information about the event is sent via POST to a specified endpoint URL over HTTPS.
Webhooks can be configured against a clients program which will be triggered each time one or more subscribed events occurs.
Components of a Webhook
A webhook has three components. A name, an endpoint URL, and a secret key.
- Name: The name is simply a reference. It can contain any string value.
- Endpoint URL: This is the URL to which we will send the POST data when the event occurs. This must be a valid URL.
- Secret Key: This secret key will be used to generate a signature header that the client may use to verify the hook data was sent from Reward Gateway.
Events and Payloads
When configuring a webhook, our clients can choose which events they would like to receive payloads for. Only subscribing to the specific events clients plan on handling is useful for limiting the number of HTTP requests to their server. Clients can change the list of subscribed events through Reward Manager at anytime.
Each event corresponds to a certain set of actions that can happen on their program. For example, if our clients subscribe to the 'authentication_success' event they'll receive a detailed payload every time an employee logs into the program.
Each event type has a specific payload format with the relevant information. All event payloads mirror the example payloads documented for each type in Webhook Events, Attributes and Payload Formats, read more in the article Webhook Events, Attributes and Payload Formats.
Delivery Headers
HTTP POST payloads that are delivered to a clients webhook's configured URL endpoint will contain several special headers:
| Header | Description |
| X-Delivery | a GUID to identify the delivery (RFC 4122) |
| X-Signature | The HMAC hex digest of the payload. The HMAC hex digest is generated using the sha1 hash function and the Secret as the HMAC Key. |
Example Delivery:
POST /payload HTTP/1.1
Host: localhost
X-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
X-Signature: 7d38cdd689735b008b3c702edd92eea23791c5f6
Content-Type: application/json
Content-Length: 6615
Configuring a Webhook on a client Program
Access Reward Manager
To be able to configure a Webhook on Reward Gateway, our clients must first have an Administrator account that will enable them to access Reward Manager.
If no credentials have been provided to access Reward Manager, please request them from one of our Implementation Specialists.
Add THE First Webhook
Once, logged in access the Webhook section located under the Integrations menu. Here, clients can add, edit and subscribe different events to their Webhook using this interface.
Testing THE Webhook
Now that the Webhook has been configured, we recommend that these be tested. Reward Manager provides some tooling for testing your deployed payloads through the recent deliveries section.
Every webhook has its own "Deliveries" section, which lists, at a glance whether a webhook delivery was successful or not.
Disabled Webhooks
If a webhook is disabled (via Reward Manager), it will not trigger when the event occurs.