The Benji Platform webhooks allow you to receive updates in near real time on activities in your partnership ecosystem. The following webhook entities are supported:
-Users : Updates on a user’s partner connect status and lifecycle on the Benji Platform.
-Campaigns : Updates to relevant campaigns and their lifecycle on the Benji Platform
-Transactions : Updates on reward transaction statuses and lifecycle.
In order to optionally authenticate and validate that the webhook was received from the Benji Platform, Benji provides a header value representing a signature that you can then validate.
The signature is essentially the webhook body, signed with the salt provided in the response from the subscribe endpoint, using a HMAC SHA-256 (HS256) algorithm.
To authenticate the webhook, you can go through the following steps :
Store the salt returned in the subscribe API call.
When receieving a webhook, use the salt to create a signature using the body of the webhook and the salt from the previous step using the HS256 algorithm.
Extract the provided signature from the x-benji-signature header value
Compare your signed body and the siganture provided, and continue processing the webhook only if the signatures match.
The webhook will also contain a header including the datetime in GMT format of the event. Typically, you can use this field to validate that this webhook is not a replay event.
A typical webhook flow requires the following steps :
Subscribe to an event and register your webhook endpoint. The Benji Platform will send any updates to this event to this endpoint using a POST request.
Listen to any webhooks on your registered webhook event endpoint
Call the Benji Platform API to retrieve additional information on the entity based on the event and the entity_type parameters in the webhook.
user_partner_connected : Indicating a user has succefully connected with a partner through the Benji Platform
Typically after receiving a user entity webhook event, you will interact with the get user status endpoint using the entity_id from the webhook to receive additional user data
campaign_updated : Indicating a campaign that you are associated with has been updated
campaign_activated : Indicating a campaign you are associated with has been activated (either manually or by reaching its scheduled date)
campaign_ended : Indicating a campaign has ended (either manually or by surpassing it’s end date)
Typically after receiving a campaign entity webhook event, you will interact with the get campaign endpoint using the entity_id from the webhook to receive additional campaign data
transaction_status_updated : Indicating a transaction has been updated, typically meaning a status change on the transaction
Typically after receiving a transaction entity webhook event, you will interact with the get reward transaction endpoint using the entity_id from the webhook to receive additional transaction data