Learn how to create and customize Webhooks in your Referral Program

What is a Webhook?
Webhooks are "user-defined HTTPS callbacks" triggered by events, in this case, from your Referral Program with Genius Referrals.

Some things to keep in mind:

  • An HTTPS POST is sent to each subscription URL with relevant data, in JSON format, when an event is triggered, for example, registering a new member, bonus, or reward.
  • By subscribing to a Webhook, your application can execute code immediately after specific events occur in your Referral Program.
  • A Webhook's delivery is considered " successful" when Genius receives a response status of 200. Otherwise, Genius continuously retries to deliver the Webhook after a time interval. For 48 hours, the Webhook is retried; during this period, Genius tries to deliver the Webhook 20 times in total. Here is how it works: 
    1- Genius waits 2 seconds when sending payload; if there is no response or there is an error, Genius tries 4 times again in the first minute, that is, every 15 seconds.
    2- The remaining 16 times will be sent in groups of 4 with 1 hour and a half difference between each group. The first group will be sent every 1½ hours and the last 4 every 4½ hours.
Note: To test this integration, there are several online services you can use to create payload URLs, such as:

Creating Webhooks
Adding a webhook will send a POST request to the URL you define with details of each selected event. To create a webhook, you must first:

  1. Log in to your Genius Referrals account.
  2. Click on the Integration section located in the navigation menu on the left side.
  3. From there, click on the Webhooks tab and then Add webhook. Follow the steps below to create the Webhook.

General information

  • Payload URL
You must enter the URL of the server that will receive the webhook POST requests.

  • Content Type
Select the Content Type to deliver. Webhooks can be delivered using different content types:

  • The application/json is content type as a POST request.
  • The application/x-www-form-urlencoded content type as a payload form parameter.


  • Secret
The secret allows you to ensure that POST requests sent to the payload URL are from Genius Referrals. You'll receive the X-Genius-Referrals-Signature-256 header in the webhook POST request.

  • SSL Verification
If your "Payload URL" is a secure site (HTTPS), you will have the option to configure the SSL verification settings. If your "Payload URL" is not secure (HTTP), Genius Referrals will not display this option. By default, Genius Referrals verifies the SSL certificate of your website when delivering webhook payloads. SSL verification helps ensure that hook payloads are delivered to your URL endpoint securely. You have the option to disable SSL, but we recommend keeping Enable SSL verification selected.


Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on your referral program, which your server's payload URL intercepts and acts upon.

  • Active
Indicates if the Webhook is active or not. You can choose to disable the delivery of webhook payloads by deselecting "Active".

When finished, click the button Save.
Editing and Deleting a Webhook
The Webhooks will be displayed in a list in which you can Edit and Delete, respectively.

  1. Find the Webhook you want to modify.
  2. Click on the three dots (...) to access the Edit and Delete actions.
  3. In the case of Edit, always remember to save the changes.
  4. For Delete, you will always be asked for confirmation before performing the action.
Webhooks are displayed in a list in which you can view the Deliveries from the actions of each Webhook.

  1. Find the Webhook you want to review.
  2. In the actions (...), click on Deliveries.
  3. The system will list all the deliveries sorted by delivery date and status (Sent, Resent, Failure).
Delivery details

Within the list of deliveries, you can view the individual details of each delivery. Including the request and the response. Click the three dots (...) and then click View details.

  • Request
The Request tab provides you with information on the Headers that were sent and details about the Payload.
  • Response
The Response tab lists how your server responded once it received the payload and the response status code. It provides information about the Headers and any additional data within the Body of the response.

  • Redeliver a Webhook
If a Webhook delivery fails, the system will automatically send it again, taking into account the frequency already established. However, if you want to resend the delivery again manually, you can do it by following these steps:

1- Click on the "Redeliver" button within the delivery details section to redeliver the event.
2- Confirm the action.
Was this page helpful?