​
Overview

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.

​
Webhook Format

All webhooks contain the following JSON body parameters :

​
event
string
required
The name of the event

​
entity_type
integer

Integer representing an enum of one of the following entity type values :

​
entity_id
integer
The ID of the entity

​
Webhook Authentication

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.

​
x-benji-signature
string
Signature described above
​
x-webhook-datetime
string
String representing the datetime in GMT format of the event

​
Webhook body sample

{
    "event": "reward_transaction_updated",
    "entity": 3,
    "entity_id": 243
}

​
Webhook Flow

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.

​
Supported events

The following events and their corresponding entity types are supported :

​
User Events

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 Events

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 Events

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