Setting up webhooks

Webhooks allow your application to subscribe to events within Recrubo. These events will primarily be related to changes in resource data. Currently, the available events are:

• create

• update

• delete

Once an event occurs on a resource, and a webhook is present, a call will be made to the defined webhookUrl where a payload will be delivered containing the resource and event.

webhookUrl can be set both on the Organization and Webhook itself, see Setup for more information

Payload

The payload is delivered in the following format:

{
    "data": {
        "type": "webhookPayload",
        "id": "<uuid>",
        "attributes": {
            "webhookId": "<uuid>",
            "event": "<string>",
            "fields": "<optional array of updated fields>",
            "resource": "<jsonapi spec formatted object>"
        }
    }
}

The type key will always be "webhookPayload" which is not an actual resource within our system. The id references a WebhookLog which is used to track the status of the payload. In case the first attempt fails we will retry 5 times over a period of 24 hours, you can find the errors returned by the receiving service on the WebhookLog using the provided id.

Moving on to the attribute key; this holds a reference to the Webhook that triggered this event, the event, fields and the resource state after the event took place.

An example of a webhook payload for the create event on the candidate resource:

{
  "data": {
    "type": "webhookPayload",
    "id": "b6445194-8a33-433e-bad2-89c6463eb620",
    "attributes": {
      "event": "create",
      "resource": {
        "id": "0970562b-5231-406a-a4b3-2b976c0bfc18",
        "type": "candidates",
        "attributes": {
          "createdAt": "2024-04-15T00:00:00+00:00",
          "updatedAt": "2024-04-15T00:00:00+00:00",
          "firstName": "Recrubo",
          "lastName": "Developer",
          "email": "[email protected]"
        },
        "relationships": {
          "organization": {
            "links": {
              "related": "/public/v2/organizations/f034e98b-591d-48d6-9fb1-903808deebe5"
            }
          }
        }
      }
    }
  }
}

The general structure follows the JSON API specification, just like the rest of the Recrubo Api. The resource-attribute is also formatted as its own JSON API resource.

Setup

To create, trigger, process and track a Webhook you first need to define a destination on either your Organization or the Webhook itself. Once this is done you create the Webhooks you need.

If you do not intend to use 1 endpoint to process multiple webhooks it is still highly recommended that you define a 'fallback' url on the organization to catch and log any 'stray' or unintentional Webhooks.

When updating your Organization resource you need to provide both a webhookUrl and webhookSecret, the webhook secret will be provided as a header on every payload we deliver under X-Recrubo-Webhook-Secret. This way you can verify that the data came from the Recrubo server.

Once this is done you can create the webhook with POST public/v2/webhooks and the following payload:

{
    "data": {
        "type": "webhooks",
        "attributes": {
            "event": "update",
            "resource": "vacancy",
            "fields": ["title", "description"],
            "webhookUrl": "https://your.webhook.com/handle-vacancy"
        }
    }
}

The fields key is optional and only has an impact when using the update event; it allows you to specify on which attribute changes the webhook should trigger. webhookUrl key is also optional and allows you to specify the delivery url for this specific webhook.

Attribute	Description	Example	Required
event	The event on which the webhook should trigger.	"create"	true
resource	The resource on which the webhook should trigger.	"vacancy"	true
fields	An array of fields/attributes on which the 'update' event should trigger.	["firstName", "postalCode"]	false
webhookUrl	The url to which the payload should be delivered, defaults to the webhookUrl on your organization.	"https://your.webhook.com/handle-vacancy"	false