Part of Xkit's design is to allow developers to separate the part of their architecture that deals with the end-user experience of connecting apps from the the part of their architecture that actually calls the APIs of those apps.

In order to support that design, Xkit makes important events available as webhooks, so that developers can register webhook listeners and process data from 3rd party APIs without having any interaction with the user experience whatsoever.

Technical Design

Xkit's Webhooks use the REST Hooks design pattern.

Webhooks are registered against specific event types, which are strings in the form of noun.verb.

When an event happens for which a webhook is registered, Xkit will make a POST request against the registered URL with a JSON body containing the event_type, and a payload.

Each event type has a specific payload it carries with it. These payloads by design carry only the minimum amount of data for you to identify the action that has taken place and query for additional data from the Platform API.

Your registered Webhook URL must respond to the Webhook with a 2XX response. If it fails for any reason, the Webhook will be retried with exponential backoff for an indeterminate number of total attempts.

POST /your/webhook/url HTTP/1.1
Accept: application/json
Host: your-domain.com
Content-Type: application/json

{
  "event_type": "connection.enabled",
  "payload": {
    "connector": {
      "slug": "github-oauth"
    },
    "context": {
      "external_id": "jFGlE7LIClQ30kdcFXb5epTDetC2"
    }
  }
}