Webhooks

We provide a comprehensive set of webhooks that allow you to receive notifications for every resource in the API. We strongly recommend using webhooks to keep your data in sync and avoid polling for changes.

You are able to subscribe to the following events:

• resource created

• resource updated

• resource deleted

We provide subscriptions for complete resources and for specific fields of a resource.

Setting up a webhook URL

Before receiving any notifications, you need to set up a webhook URL. You can do this by sending a PATCH request to the /organizations endpoint to update the "webhookUrl" and "webhookSecret" field. We will include the webhook secret in the request headers to ensure that the request is coming from us.

{
  "data": {
    "type": "organizations",
    "attributes": {
      "webhookUrl": "https://example.com/webhooks",
      "webhookSecret": "mysecret"
    }
  }
}

Example of a webhook payload

{
  "data": {
    "type": "webhookPayload",
    "id": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
    "attributes": {
      "event": "update",
      "fields": ["status"],
      "resource": {
        "id": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
        "type": "flowRuns",
        "attributes": {
          "messageThreadId": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
          "flowId": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
          "status": "finished",
          "cost": 1,
          "state": {
            "session": {
              "vacancyId": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e"
            }
          },
          "createdAt": "2021-01-01T00:00:00Z",
          "updatedAt": "2021-01-01T00:00:00Z"
        },
        "relationships": {
          "flow": {
            "data": {
              "id": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
              "type": "flows"
            }
          },
          "messageThread": {
            "data": {
              "id": "5f4e3d3e-3b3e-4e3d-8e3e-3e3e3e3e3e3e",
              "type": "messageThreads"
            }
          }
        }
      }
    }
  }
}

See Setting up webhooks for a complete guide to webhooks.