# Webhooks

Got a use case where Webhooks make the most sense? Drop us a line and we'll get you set up!

## Payload

All requests sent by ChainVine have the following structure. Each event may or may not provide a unique nested event.data payload:

```typescript
type WebHookRequestData = {
  source: {
    campaign: {
      name: string;
      created_on: string;
      id: string;
    };
    community: {
      name: string;
      id: string;
    };
  };
  event: {
    name: string;
    data: object;
  };
  version: string;
  secure_request: boolean;
  request_id: string;
  event_id: string;
  sent_at: string;
};
```

## Events

### Join Campaign Event

<details>

<summary>Payload</summary>

```typescript
{
  event: {
    name: "USER_JOINED_CAMPAIGN";
    data: {
      user_id: string;
      user: {
        id: string;
        email?: string;
        first_name?: string;
        last_name?: string;
        wallet_address?: string;
        external_identifier?: string;
      };
      referrer?: string;
      external_identifier?: string;
    }
  }
}
```

</details>

#### When we send this event

ChainVine sends this event when a user has joined a referral program.

This can occur when:

* a user clicks "Join Campaign" in a program page
* your systems call [ChainVineUser.joinCampaign](/developers/sdk/classes-and-functions/chainvineuser/joincampaign-campaignparams.md) and the request is successful&#x20;

### Referral Conversion Event

<details>

<summary>Payload</summary>

```typescript
{
  event: {
    name: "REFERRAL_CONVERSION",
    data: {
      claimer: string;
      referrer?: string;
      external_identifier?: string;
    };
  };
}
```

</details>

#### When we send this event

This event is sent whenever a ***referred*** user has completed an action:&#x20;

* you call either [ChainVineUser.verifyRequirement ](/developers/sdk/classes-and-functions/chainvineuser/verifyrequirement-payload.md)or [ChainVineUser.completeRequirement](/developers/sdk/classes-and-functions/chainvineuser/completerequirement-payload.md) methods, and this results in a claimer completing an objective or requirement
* you call [ChainVineUser.transferEvent](/developers/sdk/classes-and-functions/chainvineuser/transferevent-payload.md) where the amount transferred meets the minimum threshold (if any)
* a user completes an objective via an on-chain requirement

### Earning Creation Event

<details>

<summary>Payload</summary>

```typescript
{
  event: {
    name: "EARNING_CREATED",
    data: {
      userId: string;
      dateCreatedUtc: string;
      user: {
        id: string;
        email?: string;
        firstName?: string;
        lastName?: string;
        walletAddress?: string;
        externalIdentifier?: string;
      };
      reward: {
        name: string;
      };
      amount: string;
    };
  };
}
```

</details>

#### When we send this event

This event is fired off whenever a user reward has been attributed a reward from a program or campaign you manage.

**Schema**

| Name        | Type   | Description                                                                                                                                                              |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_id    | string | The Chainvine user id of your user                                                                                                                                       |
| reward.name | string | <p>The name of the reward issued<br>If </p>                                                                                                                              |
| amount      | string | <p>The amount of the reward issued.<br>Cryptocurrencies: 18 decimal places, value in unitary currency (ie, in ETH, not GWEI)<br>Non Crypto Rewards: 4 decimal places</p> |

**Examples of reward amounts**

* "15.000" Points for fifteen points
* "0.00398888889000003983" ETH for 0.0039 ETH
* "1.000" NFT for 1 NFT of a Collection
* "1.000" Boxes for 1 Loot Box from your platform

### Payment Request

ChainVine supports using your system as a payout-provider if you should so choose.

Example scenarios where this could be a useful scenario for you:

* if you have compliance requirements to track, record or action all user payouts
* if you have a payout currency not supported by ChainVine

#### When we send this event

This event is sent in one of the following scenarios if you have configured a reward payout to be managed by your systems:

* a user clicks "Claim Rewards" on ChainVine or on the ChainVine Widget hosted on your site
* if you have configured payouts to be automatically executed as soon as they are awarded to users.

#### Handling responses

ChainVine will expect a 200-type status to mark a payment as completed.

If an error response is received, ChainVine will mark the payout as failed, and the payout will need to be attempted again.&#x20;

There is currently no limit on how many times a Webhook Payout can be attempted.

## Testing

If you would like to test the webhook flow before implementing on your end, simply visit <https://webhook.site/> and send us your unique URL.\
\
We will then configure your community's webhooks to target your unique endpoint and you can inspect them as they come through.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chainvine.xyz/developers/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.