Receiving Webhook Events

Receiving a webhook

The first step to adding webhooks to your Prefinery integration is to build your own custom endpoint. Creating a webhook endpoint on your server is no different from creating any page on your website.

Webhook data is sent as JSON in the request's body. The full event details are included and can be used directly. When an event occurs in Prefinery, we'll POST to your URL with a payload of JSON-encoded data.

Responding to a webhook

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

If you reply with a HTTP 429 then we will mark the webhook as retrying and retry delivery using the logic below. If you reply with a HTTP 410 then we will mark the webhook as failed and remove the endpoint from your project. If you reply with any another response code, we will mark the webhook as rejected.

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

Tip — Return a HTTP 200 status code quickly and schedule any action or complex logic to be taken on the webhook payload asynchronously.

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.

It is not possible to manually retry a failed webhook.

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

List of webhook events

The following is a list of events we currently support.

tester_created
A user has been created.
tester_updated
A user has been updated. Note: A change in list position does not trigger this event.
tester_imported
A user has been imported.
tester_applied
A user has applied.
tester_invited
A user has been invited.
tester_rejected
A user has been rejected.
tester_activated
A user has been activated.
tester_suspended
A user has been suspended.
tester_deleted
A user has been deleted.
tester_unsubscribed
A user has unsubscribed from receiving emails.
tester_resubscribed
A user has resubscribed to receive emails.
referral_created
A user has referred a friend.
ping
May be sent by Prefinery at any time to see if a provided webhook endpoint is working.

Note — Prefinery does not send webhooks for hidden users. Any users created in excess of your subscription limit will be hidden until you upgrade your subscription. Please subscribe to the Business plan if you want to ensure users are always visible and no webhook events will be lost.

Sample payloads

          
{
  "id": 123,
  "type": "tester_created",
  "data": {
    "id":1259,
    "project_id":1,
    "email":"bruce@wayneenterprises.com",
    "status":"applied",
    "imported_at":null,
    "applied_at":"2012-09-06T23:29:20Z",
    "created_at":"2012-09-06T23:29:20Z",
    "updated_at":"2012-09-06T23:29:20Z",
    "invited_at":null,
    "joined_at":null,
    "invitation_code":"",
    "share_clicks_count":0,
    "share_signups_count":0,
    "share_link":"http://l.aunch.us/FaKElInK",
    "referred_by":null,
    "game_code":null,
    "friend_invitations_count":0,
    "friend_invitations_remaining":5,
    "profile":{
      "first_name":"Bruce",
      "last_name":"Wayne",
      "gender":"Male",
      "age":"39",
      "employer":"Wayne Enterprises",
      "jobtitle":"CEO",
      "telephone":"300-555-0169",
      "ip":"64.71.141.151",
      "address_line1":null,
      "address_line2":null,
      "city":"Gotham",
      "state":"NJ",
      "postal_code":"07470",
      "country":"United States",
      "facebook_username":null,
      "linkedin_username":"brucewayne",
      "twitter_username":"bruce",
      "http_referrer": "https://www.google.com",
      "utm_source": "Google",
      "utm_medium": "cpc",
      "utm_campaign": "charity_benefit",
      "utm_term": "bruce+wayne+charity+benefit",
      "utm_content": "banner"
    }
  },
  "created_at": 1346878649
}
          
        
          
{
  "id": 123,
  "type": "referral_created",
  "data": {
    "project_id":1,
    "source":"Facebook",
    "created_at":"2012-09-06T23:29:20Z", 
    "referring_user": {
      "id":1259,
      "email":"bruce@wayneenterprises.com",
      "status":"applied",
      "imported_at":null,
      "applied_at":"2012-09-06T23:29:20Z",
      "created_at":"2012-09-06T23:29:20Z",
      "updated_at":"2012-09-06T23:29:20Z",
      "share_clicks_count":10,
      "share_signups_count":1,
      "share_link":"http://l.aunch.us/FaKElInK",
      "profile":{
        "first_name":"Bruce",
        "last_name":"Wayne",
        "gender":"Male",
        "age":"39",
        "employer":"Wayne Enterprises",
        "jobtitle":"CEO",
        "telephone":"300-555-0169",
        "ip":"64.71.141.151",
        "address_line1":null,
        "address_line2":null,
        "city":"Gotham",
        "state":"NJ",
        "postal_code":"07470",
        "country":"United States",
        "facebook_username":null,
        "linkedin_username":"brucewayne",
        "twitter_username":"bruce",
        "http_referrer": "https://www.google.com"
      }
    },
    "referred_user": {
      "id":1362,
      "email":"robin@wayneenterprises.com",
      "status":"applied",
      "imported_at":null,
      "applied_at":"2012-10-07T23:29:20Z",
      "created_at":"2012-10-07T23:29:20Z",
      "updated_at":"2012-10-07T23:29:20Z",
      "share_clicks_count":0,
      "share_signups_count":0,
      "share_link":"http://l.aunch.us/FaKElInK",
      "profile":{
        "first_name":"Robin",
        "last_name":"",
        "gender":"Male",
        "age":"18",
        "employer":"Wayne Enterprises",
        "jobtitle":"Sidekick",
        "telephone":"300-555-0169",
        "ip":"64.71.141.151",
        "address_line1":null,
        "address_line2":null,
        "city":"Gotham",
        "state":"NJ",
        "postal_code":"07470",
        "country":"United States",
        "facebook_username":null,
        "linkedin_username":"boywonder",
        "twitter_username":"boywonder"
      }
    }
  },
  "created_at": 1346878649
}
          
        
          
{
  "id": 123,
  "type": "reward_earned",
  "data": {
    "id":123,
    "descriptor":"50_OFF",
    "name":"50% off",
    "project_id":1,
    "user_id":1259,
    "user_role","referrer"
    "status":"earned",
    "type":"SingleSided",
    "earned_at":"2012-09-06T23:29:20Z",
    "delivered_at":null,
    "revoked_at":null
    "user": {
      "id":1259,
      "email":"bruce@wayneenterprises.com",
      "status":"applied",
      "imported_at":null,
      "applied_at":"2012-09-06T23:29:20Z",
      "created_at":"2012-09-06T23:29:20Z",
      "updated_at":"2012-09-06T23:29:20Z",
      "share_clicks_count":10,
      "share_signups_count":1,
      "share_link":"http://l.aunch.us/FaKElInK",
      "profile":{
      "first_name":"Bruce",
      "last_name":"Wayne",
      "gender":"Male",
      "age":"39",
      "employer":"Wayne Enterprises",
      "jobtitle":"CEO",
      "telephone":"300-555-0169",
      "ip":"64.71.141.151",
      "address_line1":null,
      "address_line2":null,
      "city":"Gotham",
      "state":"NJ",
      "postal_code":"07470",
      "country":"United States",
      "facebook_username":null,
      "linkedin_username":"brucewayne",
      "twitter_username":"bruce",
      "http_referrer": "https://www.google.com"
    }
  },
  "created_at": 1346878649
}
          
        

Test a webhook endpoint

There are several ways to test that your webhook endpoint is working properly before taking it live:

Create test activity on your account

  1. First, add the endpoint to your account by following this guide.
  2. Take some action, for example submitting your Signup Form in order to generate the tester_created event.

Manually send test events from your account

  1. First, add the endpoint to your account by following this guide.
  2. After adding the endpoint, click the Test button.

Note that test webhooks will not show up in the Event Log inside your account.

Troubleshooting

We recommend using Mockbin or Webhook.site to troubleshoot webhooks.