Webhooks can be created on the Settings > API page.

Payload

The payload for a webhook is an Event object with the following properties:

eventType string
The event type that triggered this webhook.

created string
The date this webhook event is sent.

object string
The object type of the item being sent in this webhook event.

data map
A resource object associated with this webhook event. The type of this resource is specified in the object property.

Response

Copilot expects to receive an HTTP 200 response code from your endpoint. We will retry to deliver the message 3 times if we don't receive one. To prevent time-outs, it is wise to configure your endpoints to send a 200 and then do any long-running processing on the data.

Security

Copilot supports securing webhooks by including a signature in each event's x-copilot-signature header. This allows you to verify that the events were sent by Copilot and not by a third-party.

To verify the webhook, compute the signature from the request body using the webhook signing secret which can be revealed from the webhook menu.

It's recommended to use raw request body content for the hashing as using JSON parsing might change it.

const crypto = require('crypto');

const signature = crypto.createHmac("sha256", SIGNING_SECRET).update(rawBody).digest("hex");
if (signature !== request.headers['x-copilot-signature']) {
  throw "Invalid signature"
}