Webhook Events

​

Methods

​

Subscribe

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

• 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.

• 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: 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

• 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)

• 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.

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

// 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

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

// 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

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

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

// 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
  }
}