> ## 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:
**event** `string` *required* The name of the event

**entity\_type** `integer`

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

**possible entity type values**

* **USER (1)** : Indicating a user entity \\

* **CAMPAIGN (2)** : Indicating a campaign entity  \\

* **TRANSACTION (3)** : Indicating a reward transaction entity

**entity\_id** `string`

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](https://docs.withbenji.com/api-reference/webhooks/subscribe.md), 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.

**x-benji-signature** `string`

Signature described above

**x-benji-timestamp** `string`

String representing the datetime in GMT format of the event

### 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](https://docs.withbenji.com/api-reference/webhooks/subscribe.md)** 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

**User Events**

* user\_partner\_authentication\_created : Indicating a user has successfully connected with a partner through the Benji Platform

> [!TIP]
>
> Typically after receiving a user entity webhook event, you will interact with the [get user status](https://docs.withbenji.com/api-reference/endpoint/status/get) endpoint using the entity\_id from the webhook to receive additional user data.

#### Campaign Events

**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)

> [!TIP]
>
> Typically after receiving a campaign entity webhook event, you will interact with the [get campaign](https://docs.withbenji.com/api-reference/endpoint/campaigns/get) endpoint using the entity\_id from the webhook to receive additional campaign data.

#### Transaction Events

**Transaction Events**

* transaction\_authenticated : Indicating a [transaction authentication token](https://docs.withbenji.com/api-reference/endpoint/transactions/authenticate) has been created
* transaction\_created : Indicating a [transaction has been created](https://docs.withbenji.com/api-reference/endpoint/transactions/create)
* transaction\_status\_updated : Indicating a transaction has been updated, typically meaning a status change on the transaction

> [!TIP]
>
> Typically after receiving a transaction entity webhook event, you will interact with the [get reward transaction](https://docs.withbenji.com/api-reference/endpoint/transactions/get.md) endpoint using the entity\_id from the webhook to receive additional transaction data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.