🪝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:

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

Payload

{
  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;
    }
  }
}

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 and the request is successful

Referral Conversion Event

Payload

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

When we send this event

This event is sent whenever a referred user has completed an action:

• you call either ChainVineUser.verifyRequirement or ChainVineUser.completeRequirement methods, and this results in a claimer completing an objective or requirement

• you call ChainVineUser.transferEvent where the amount transferred meets the minimum threshold (if any)

• a user completes an objective via an on-chain requirement

Earning Creation Event

Payload

{
  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;
    };
  };
}

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	The name of the reward issued If
amount	string	The amount of the reward issued. Cryptocurrencies: 18 decimal places, value in unitary currency (ie, in ETH, not GWEI) Non Crypto Rewards: 4 decimal places

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.

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.