Global Webhook Events

This method of collecting events is used when an External App uses a single webhook per connected application rather than allows creating any number of connection-layer webhooks. In this case, the single webhook should be configured by the developer of the connected application and events received through this webhook need to be routed to a correct Customer and Connection but the Global Webhooks mechanism.

This mechanism consists of two parts:

• Global Webhook definition inside a Connector.
• External Event definition with global-webhook implementation type.

When a connector with global webhooks is used in an Integration, a unique global webhook URI is generated for each global webhook defined in the connector. You can find the corresponding webhook URIs by using Get integration webhooks API endpoint.

Global Webhook Definition

Global webhooks are defined inside a Connector. They are defined as connector files inside global-webhooks directory, for example:

// Connector files
global-webhooks/webhook-key/spec.yml // Global Webhok definition
global-webhooks/webhook-key/handle.js // Implementation of the "handle" function.

The developer needs to take this URL and provide it to the external app as a webhook (usually as part of the OAuth application configuration).
You should provide details on how to do this in the connector documentation.

spec.yml

Global webhook specification looks like this:

name: Webhook Name
key: webhook-key
methods:
  handle:
    implementationType: javascript

handle

The handle function is called when data is sent to the webhook.

Example:

export default async function handle({ data }) {
  return {
    events: [
      {
        payload: data,
        selector: `user_id:${data.from_user_id}`,
      },
    ],
    response: {
        status: 201,
        data: "Webhook received"
    }
  }
}

Arguments:

• query – object, webhook request query received from the external app
• data – object, webhook request body received from the external app (parsed based on Content-Type)
• headers – object, webhook request headers received from the external app
• parameters – connector parameters configured on the integration the webhook belongs to
• rawBody – string, raw unparsed body of the webhook request (useful for signature verification or when you need access to the original request body)

Result:

• events – list of events. Each event has the following properties:
  • selector (string) – selector to find matching external event subscriptions (see External Events)
  • payload – arbitrary event payload that will be passed to matched subscriptions.
• response – object, optional HTTP response with properties:
  • headers – object
  • status – number
  • data – HTTP body (based on Content-Type)

Global Webhook Event

External Events implemented through global webhook look like this:

// events/event-key/spec.yml
name: Event Name
implementationType: global-webhook
key: event-key
methods:
  get-event-selector:
    implementationType: javascript

Functions

The following functions can be implemented for events with global-webhook implementation type:

getEventsSelector

This method returns data that will be used to route the event to the correct connection.

Supported implementation types: javascript, mapping

Example:

export default async function getEventSelector({ apiClient }) {
  const response = await apiClient.get('users/me')
  return {
    globalWebhookKey: 'global-webhok-key',
    globalWebhookEventSelector: `user_id:${response?.id}`,
  }
}

Function arguments:

• parameters – object of parameters (matching parametersSchema) of this particular event.

Return value is an object with the following fields:

• globalWebhookKey – key of the global webhook defined in the connector (see Global Webhooks)
• globalWebhookEventSelector – string that is used to route the event to the correct subscription. This string typically needs to be generated dynamically based on the event parameters and information we can get from the current connection (using apiClient or credentials).

When a global webhook handles a payload and returns events, it will be routed to a given External Event Subscriptions if:

• globalWebhookKey returned from this method matches the key of the global webhook
• globalWebhookEventSelector returned from this method matches the event selector associated to the event returned by the handle method of the global webhook.