> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withbenji.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Benji Platform Webhooks Overview

> An overview of the Benji Platform webhooks, allowing you to receive real-time updates on users, campaigns, and reward transactions.

## 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:
<ParamField body="event" type="string" required>The name of the event</ParamField>

<ParamField body="entity_type" type="integer">
  Integer representing an enum of one of the following entity type values:

  <Expandable title="possible entity type values" type="enum">
    * **USER (1)** : Indicating a user entity <br />
    * **CAMPAIGN (2)** : Indicating a campaign entity  <br />
    * **TRANSACTION (3)** : Indicating a reward transaction entity
  </Expandable>
</ParamField>

<ParamField body="entity_id" type="string">The ID of the entity</ParamField>

### 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](/api-reference/webhooks/subscribe), using an 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 receiving a webhook:
  * Extract the timestamp from the x-benji-timestamp header value.
  * Create the signature input by concatenating: **timestamp** and **body**.
  * Generate a signature using HMAC SHA-256 with your stored salt: HMAC-SHA256(salt, concatenated timestamp and body string).
* Extract the provided signature from the x-benji-signature header value.
* Compare your signed body and the signature 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.

<ParamField header="x-benji-signature" type="string">Signature described above</ParamField>
<ParamField header="x-benji-timestamp" type="string">String representing the datetime in GMT format of the event</ParamField>

### Webhook body sample

```json theme={null}
{
    "event": "reward_transaction_updated",
    "entity": 3,
    "entity_id": "55af7b67-bf3c-4fbf-81bc-05db9426ca96"
}
```

### Webhook Flow

A typical webhook flow requires the following steps:

* **[Subscribe to an event](/api-reference/webhooks/subscribe)** 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

<Expandable title="User Events">
  * user\_partner\_authentication\_created : Indicating a user has successfully connected with a partner through the Benji Platform
</Expandable>

<Tip>Typically after receiving a user entity webhook event, you will interact with the [get user status](/api-reference/endpoint/status/get) endpoint using the entity\_id from the webhook to receive additional user data</Tip>

#### Campaign Events

<Expandable title="Campaign Events">
  * 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 its end date)
</Expandable>

<Tip>Typically after receiving a campaign entity webhook event, you will interact with the [get campaign](/api-reference/endpoint/campaigns/get) endpoint using the entity\_id from the webhook to receive additional campaign data</Tip>

#### Transaction Events

<Expandable title="Transaction Events">
  * transaction\_authenticated : Indicating a [transaction authentication token](/api-reference/endpoint/transactions/authenticate) has been created
  * transaction\_created : Indicating a [transaction has been created](/api-reference/endpoint/transactions/create)
  * transaction\_status\_updated : Indicating a transaction has been updated, typically meaning a status change on the transaction
</Expandable>

<Tip>Typically after receiving a transaction entity webhook event, you will interact with the [get reward transaction](/api-reference/endpoint/transactions/get) endpoint using the entity\_id from the webhook to receive additional transaction data</Tip>