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.
NOTE: The Webhook integration is only available for promotions created with the White Label 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 two different types of events:
- 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.
- 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.
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 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 Version: Select the version in which you want to receive the information from the Webhooks.
- Version 2.0 (recommended): this is the last version, available since April 2022. Its definition and specification follow the Openapi 3.1 standard.
- Version 1.0 (obsolete): Initial version of the Easypromos Webhooks, which is maintained for compatibility with old promotions and integrations.
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.
d) 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. This type of event is only available in promotions that have the Login system enabled.
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.
- 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 to test webhooks:
- Open requestbin.com
- Click to create a new Request. You will need to login with a Github or Google account.
- 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).