Webhook

Webhook Events

This type of event subscribes to a webhook and then receives event notifications.

Methods

The following methods can be implemented for webhook events:

Subscribe

• Method key: subscribe
• Supported implementation types: javascript, rest-api-mapping, graphql-api-mapping

This function subscribes to events in the external app.

Arguments:

• webhookUri – string, URI webhooks should be sent to. It should be passed to the external app.
• parameters – object, parameters (matching parametersSchema) of this particular event.

Result:

• state – object, subscription state. This state will be saved and passed as state to unsubscribe and handle functions.
• nextRefreshTimestamp – number, optional, timestamp in milliseconds when the next refresh should be performed. Used to refresh the subscription if the external app requires it.

Example:

// Example: Subscribe to a webhook and return the webhookId.
export default async function subscribe({ apiClient, webhookUri, parameters }) {
  const body = { webhookUri, '<some_key>': '<some_value>' }
  const response = await apiClient.post(parameters.path, body)

  return {
    state: {
      webhookId: response?.id
    }
  }
}

Handle

• Method key: handle
• Supported implementation types: javascript, mapping

This function processes notification requests from the external app.
If the external app requires a response, you can specify parameters (headers, data) for the response in the response property (optional). This can be useful if the external API requires confirmation of the webhook URI.

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
• state – object, state returned from subscribe function
• parameters – object, parameters (matching parametersSchema) of this particular event
• 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 objects, list of events extracted from the webhook. Each event is an object with type and record fields.
• response – object, optional HTTP response with properties:
  • headers – object
  • status – number
  • data – HTTP body (based on Content-Type)
• state – a new value of the state if it needs to be updated.

Example result:

{
  "events": [
    {
      "record": {
        "id": "1"
        // ...other fields that match collection fieldsSchema
      }
    }
  ],
  "response": {
    "headers": {
      "x-response-header": "header value"
    },
    "data": {
      "responseField": "value"
    }
  }
}

Example:

// Example: Handle a webhook and return events.
export default async function handle({ body, query, parameters, rawBody }) {
  // Verify webhook signature if needed
  if (query.signatureRequest) {
    const signature = createHmac('sha256', parameters.webhookSecret)
      .update(rawBody)
      .digest('hex')
    if (signature !== headers['x-webhook-signature']) {
      throw new Error('Invalid webhook signature')
    }
  }

  // Process the webhook payload
  return {
    events: [
      {
        type: 'created',  // Possible values: 'created', 'updated', 'deleted'
        record: body.record,
      },
    ],
    response: {
      headers: {
        'Content-Type': 'text/plain',
      },
      data: query?.data,
    },
  }
}

Unsubscribe

• Method key: unsubscribe
• Supported implementation types: javascript, rest-api-mapping, graphql-api-mapping

This function should send a request to delete the webhook by webhookId received in the subscribe method.

Arguments:

• state – state returned from subscribe
• parameters – object, parameters (matching parametersSchema) of this particular event

Example:

// Example: Unsubscribe from a webhook.
export default async function unsubscribe({ apiClient, state, parameters }) {
  await apiClient.delete(`${parameters.path}/${state.webhookId}`)
}

Refresh (optional)

• Method key: refresh
• Supported implementation types: javascript, rest-api-mapping, graphql-api-mapping

Some applications require refreshing the subscription to keep it active.
This method should be implemented if the nextRefreshTimestamp is returned from the subscribe method.

Arguments:

• state – state returned from subscribe
• webhookUri – string, URI webhooks should be sent to
• parameters – object, parameters (matching parametersSchema) of this particular event

Response:

• state – updated state information if it needs to be updated
• nextRefreshTimestamp – number, timestamp in milliseconds when the next refresh should be performed

Example:

// Example: Refresh a webhook subscription.
export default async function refresh({ apiClient, state, parameters }) {
  await apiClient.post(`${parameters.path}/${state.webhookId}/refresh`)
  return {
    nextRefreshTimestamp: Date.now() + 1000 * 60 * 60 * 24, // Refresh in 24 hours
  }
}