# 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](https://docs.chainvine.xyz/developers/sdk/classes-and-functions/chainvineuser/joincampaign-campaignparams) 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 ](https://docs.chainvine.xyz/developers/sdk/classes-and-functions/chainvineuser/verifyrequirement-payload)or [ChainVineUser.completeRequirement](https://docs.chainvine.xyz/developers/sdk/classes-and-functions/chainvineuser/completerequirement-payload) methods, and this results in a claimer completing an objective or requirement
* you call [ChainVineUser.transferEvent](https://docs.chainvine.xyz/developers/sdk/classes-and-functions/chainvineuser/transferevent-payload) 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.