How to use webhooks?

What are webhooks? 

Webhooks are a way than an app can send automated information to other apps. 

With Prefinery, you can use webhooks to notify and send data to your app when something happens in your project (event) like when a user signs up, is invited, refers a friend, earns a reward, etc.

Why use them? 

Our webhooks integration will allow you to perform custom actions in your own system based on information sent by a specific event in your Prefinery project. Here are some examples: 

• When a user applies for your campaign, they also get added to your own database. 
• When a user is activated, a particular feature is enabled on their account in your system. 
• When a user creates a referral, you grant them a reward in your system. 
• When a user unsubscribes, you email them a coupon.
• When a user earns a reward, you fulfill that reward. 

Webhooks can also be used to keep two or more systems in sync. For example, when a user applies for your campaign, besides getting added to your database they can also get added to your CRM software.

How to add them? 

Setting up Webhooks Integration requires you to provide your app's Webhook URL where Prefinery can POST data when an event occurs in your project. 

To do this: 

1

From your project dashboard, navigate to Integrations > Webhooks. 

2

In the Webhooks Integration page, click on the Add a URL button in the upper-right corner. 

3

In the Add a Webhook URL modal that appears, paste in your Webhook URL and in the Events dropdown select the event that you'd like to get notified about and get Prefinery to POST data to your webhook URL. Click on the Add button to complete this step.  

4

You can check that your newly added webhook is working by clicking on the Test button and getting a response code of HTTP 200. 

You can also go to your app to confirm the data sent by the test. Below is just an example showing the kind of information that Prefinery sends for a "User Invited" event.

What do they look like?

The Raw Content section in the screenshot above shows a portion of what data is send to your webhook URL for that particular event. You can also see sample payloads for various webhook event types inside your account by clicking the Docs button in the Webhooks Integration page or in our Webhooks Developer Resource (just scroll down to the "Sample payloads" section there). 

Responding

To acknowledge that you received the webhook without any problem, your server should return a  HTTP 200  status code. Any other information you return in the request headers or request body will be ignored. Once you reply with a HTTP 200  our system will mark the webhook as accepted .

If you reply with any response code that is not a HTTP 200 , including 3xx/4xx/5xx codes, we will mark the webhook as rejected .

Your server must respond within 15 seconds to prevent a timeout error.  

Retry logic

If we are unable to reach your server for any reason — such as a connection error or timeout — we will attempt to deliver the webhook over the next few days with an exponential back off. We will make 15 retry attempts, scheduled again in 5 seconds + N^4 where N is the number of attempts, until we finally abort and mark the webhook as  failed .

You cannot manually retry a failed webhook.

Failures will only affect that particular webhook event, not the Webhook URL. We will continue to attempt sending new events to your Webhook URL, even if previous webhook events have failed.

History

You can see all webhooks sent by clicking the  Event Log button. Test events (when you click on the Test button) are not logged. 

You can also see all webhooks sent to a particular user by visiting that user's profile page and clicking on their Webhooks tab.