What is a webhook?

A webhook is a system used by an application to send information to other applications in real-time. A webhook sends the information at the same time it is registered, which means that it allows you to obtain the information instantly.

In Easypromos, the webhook integration enables you to send registration data from your promotion participants to your own application. In this way, this system allows you to receive the information of the unique users and their participations in real time. You can then use your application to manage and manipulate the data according to your needs.

Examples of the use of webhooks in Easypromos:

• Receive in real time the information of a new user who registers in your promotion to add it to a CRM.
• Receive real-time information on the prize won by a user when spinning your prize wheel, to process the delivery of the prize.
• Receive real-time information about the virtual currencies earned after playing a game to synchronize them with the points program of a loyalty system.

Note: The Webhook integration is only available for promotions created with the White Label and Corporate version of the platform.

Here's how to enable webhook integration in your app:

Types of events for Easypromos webhooks

You can use Easypromos webhooks to configure and receive notifications when a specific event occurs.

There are 4 different types of events:

1. Webhook upon registering a new user: the information of a new user who registers in the promotion will be sent. In case the user has to confirm the email address to register, the webhook will be sent as soon as the users have validated their email. This webhook is ideal for receiving information from registered users in real time and inserting them into a CRM or user management system.
2. Webhook upon registering a new participation from a user: the specific information of a user 's participation will be sent. For example, the information of the prize won by a user when spinning a prize wheel, or discovering a prize in the Reveal and Win, or the points obtained by a user in a game will be sent.
3. Webhook on winning a prize: it will be sent each time a user wins a prize and includes the full information of the prize won and the details of the winning user.
4. Webhook on completing a transaction with virtual currencies: it is sent each time a transaction with virtual currencies is made. The transaction can involve a positive amount of currencies, for example, when earning currencies by participating in a stage, or a negative amount of currencies, for example, when spending currencies to exchange for prizes. The webhook includes the transaction amount, the user's balance, and the user.

Before you begin

Prior to beginning with the integration, please take into account the following considerations:

• The webhook integration is an advanced feature. A developer or someone with advanced programming knowledge will be needed to implement it.
• You will also need a server that accepts HTTP POST calls, and a way to write a script that performs an action in response.
• Webhooks can only be configured in promotions created in the White Label and Corporate version.
• You can have multiple webhooks in the same promotion, in case you want to send the information in real time to several destinations.

To configure the webhook integration you’ll need to follow the next two steps:

• Step 1 - Prepare the promotion to send the webhook: this can be done by the Marketing person who is configuring the promotion from the Easypromos management interface.
• Step 2 - Program the reception and process of the webhook: This step must be done by the IT person who will program the script or program that will receive the webhook, and will process its information.

Step 1. Prepare the promotion to send the Webhook

To carry out this step it is necessary to have access to the promotion management panel in Easypromos. This step will normally be carried out by the marketing person who manages the promotion and has access to Easypromos.

To prepare the promotion for the webhooks to be sent, integration with webhooks must be enabled from the promotion management panel in Easypromos, following these steps:

1. Access the Promotion Management Page and enter the ‘Integrations’ section:

2. Next, select the ‘Webhooks’ option to enable the integration.

3. You’ll gain access to the Webhook integration settings page. From here you’ll be able to configure the following options:

a) Webhook Type: the type of event that triggers the webhook. You have two options:

• On register a new user: The Webhook is triggered when a new user registers in the promotion. The Webhook includes all of the user's registration information.
• On register a new participation from a user: The Webhook is triggered when a new participation of a user in the promotion is registered. The Webhook includes the entry information, that of the participating user, and includes the prize information, if any prize was assigned to the entry.
• On winning a prize: The Webhook is triggered each time a prize is awarded to a user (i.e., the user wins a prize in a Wheel). The Webhook includes the prize information and the details of the user who won the prize. The Webhook does not apply to prizes awarded by Random Draw. It applies to prizes awarded by Instant Win, Direct Participation, Probability, or Redemption of virtual coins.
• On performing a transaction with virtual coin: The Webhook is triggered each time a user makes a transaction with virtual coins. The Webhook includes the transaction details and the user information. The transaction details include the transaction amount (which can be positive or negative depending on whether it was earned or spent) and the user's balance after the transaction is completed.

b) Webhook URL: This is the URL where the information will be sent.

c) Webhook Key (optional): Optionally you can add a reference to the Webhook through this alphanumeric text field. This field will be sent along with the webhook information. Use it to validate that the Webhook is indeed sent by Easypromos.

Step 2. Program the reception and process of the Webhook 

To perform this step, knowledge in web programming is required. This step will be carried out by the programmer who will develop the integration of the information obtained in Easypromos with an external system.

The information will be sent in HTTP_POST requests and the body of the message (payload) will come in JSON format.

The webhook information specification has been defined following the OpenApi 3.1 standard. Here is the access to the specification.

• On register a new user: see documentation and examples
• On register a new participation: see documentation and examples.
• On winning a prize ganar un premio: see documentation and examples
• On performing a transaction with virtual coin: see documentation and examples.

Development Considerations:

• The system will consider the attempt to send the webhook erroneous if the destination url does not respond within 3 seconds.
• The system will make 3 consecutive retries in case of an erroneous attempt. After 3 failed attempts, the assignment will be discarded and will not be submitted again.

Can I test or validate Webhooks?

Yes, you can use free online services such as requestbin.com

1. Open requestbin.com
2. Click to create a new Request. You will need to login with a Github or Google account.
3. Copy the created Request URL del Request in the configuration of the Webhook.

Then take part in the promotion as a user and check the webhook received on requestbin.com:

Can I edit or delete a Webhook?

Yes, once you have created the different webhooks, on the integrations / webhooks page, all the webhooks you have created will be displayed. They can be edited and deleted. They will be presented in a list, and with the typology of each of the webhooks (if it is a webhook of unique users or participations).