About Webhooks

Webhooks provide a way for Raisely to inform your application whenever something happens within one of your campaigns. They are real time, and available on all actions within Raisely.

If you're syncing Raisely with a CRM or external system, it's best practice to subscribe to webhooks over polling or syncing as it saves us both a lot of resources and there's less opportunity for error.

🚧

How we handle webhook failures

If your application isn't able to successfully receive our notifications we'll continue to retry 4 more times, every hour. We consider a failure to be anything without a 2xx status code, so we don't accept redirects.

If we're still not able to deliver the notification, we'll give up. After multiple failed deliveries we will disable your webhook entirely.

📘

Update Webhooks only trigger on changes to a record

Note that update webhooks (eg profile.update, donation.update) will only be triggered when the data in a record changes.
If you send a PATCH request for a record, but the data provided is the same as what is already stored on the record, you will receive a 200 response from that request, but any webhooks listening for an update event will not receive one.

Subscribing to webhooks

You can subscribe to webhooks in the Raisely admin panel or programmatically through our REST API. In the Raisely admin panel you need to:

1. Head to Settings > API & Webhooks.
2. Enter your endpoint URL, a shared secret if needed and select the events you want to subscribe to.
3. Make sure your endpoint will respond 2xx to a blank POST request. We'll validate the URL and start sending notifications immediately.

If you specify a secret, the validation request will include that secret in the Headers as Authentication: Bearer

Receiving webhooks

Raisely will post JSON to your endpoint in the following format:

{
  "secret": "myverysecretsecret",
  "data": {
  	"uuid": "xxxx-xxxx-xxxx-xxxx", // unique uuid of the event
    "type": "profile.updated",
    "createdAt": "2018-02-19T00:00:00Z", // ISO8601 timestamp of when the event was created
    "source": "campaign:uuid", // where the event originated from in the format of model:uuid
    "data": {
      "uuid": "xxxx-xxxx-xxxx-xxxx"
      // JSON representation of the model
    },
    "context": {
    	"utmSource": "facebook",
      "utmMedium": "cpc",
      "utmCampaign": "example",
      "userAgent": "...",
      "referrer": "https://facebook.com", // document.referrer of the user who made the request
      "pathname": "/my-example-page", // window.location.pathname of where the request was made
      "fbc": "...", // facebook click ID
      "fbp": "..." // facebook pixel ID
    },
    "diff": {
      "new": {
        "description": "My new description"
      },
      "old": {
        "description": "My old description"
      }
    }
  }
}

The object in the data.data key will be the same as what you get if you do a GET call to that individual resource. For example, the donation.created webhook delivery will be the same as:
GET /v3/donations/:donationUuid