Webhooks

​

What is a webhook?

ChainPatrol uses webhooks to notify you about changes to our global blocklist.

This allows you to update your blocklist in real-time, without having to wait for a scheduled cron job to run. This is especially useful if you opt to use our Asset List endpoint to sync our data as you can update your blocklist as soon as we update ours.

​

Managing Webhooks

You can manage your webhooks through the ChainPatrol dashboard under Settings > Webhooks. From here you can:

1. Create new webhooks
2. View and monitor webhook deliveries
3. Test webhooks with sample events
4. Enable/disable webhooks
5. Update webhook configurations
6. Delete webhooks

Each webhook delivery is logged and can be inspected for debugging purposes, including the full request and response details.

​

Event Types

​

debug.test

This event is used for testing your webhook endpoint. It is sent when you click the “Test” button for a webhook in the dashboard.

{
  "event": "debug.test",
  "created_at": "2023-08-31T00:00:00.000Z",
  "data": {}
}

​

asset.status-updated

This event is sent when the status of an asset changes. The status field can be one of BLOCKED, ALLOWED, or UNKNOWN.

{
  "type": "asset.status-updated",
  "created_at": "2023-08-31T00:00:00.000Z",
  "data": {
    "asset_id": 132,
    "type": "URL",
    "content": "https://example.com",
    "status": "BLOCKED"
  }
}

​

Webhook Configuration

When creating a webhook, you’ll need to provide:

1. A HTTPS endpoint URL that will receive the webhook events
2. An optional description to help identify the webhook’s purpose
3. Select which events you want to receive (currently only asset.status-updated is available)

The webhook secret will be automatically generated and shown to you once when creating the webhook. Make sure to copy it as it won’t be displayed again.

​

Signature Verification

ChainPatrol signs each webhook request with a signature to verify that the request originated from ChainPatrol. The signature is included in the X-ChainPatrol-Signature header of each request. The signature is computed by taking the SHA256 HMAC of the request body using your webhook secret as the key. The signature is encoded as a hex string.

sha256=hex(hmac_sha256(webhook_secret, request_body))

You can verify the signature of a request by computing the signature yourself and comparing it to the signature included in the request. If the two signatures match, then you can be sure that the request originated from ChainPatrol.

Here’s an example of how to verify the signature in Node.js:

const crypto = require("node:crypto");

const [, signature] = req.headers["x-chainpatrol-signature"].split("=");

const expectedSignature = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(req.body)
  .digest("hex");

if (signature !== expectedSignature) {
  throw new Error("Invalid signature");
}

​

Delivery Status and Retries

Each webhook delivery attempt is logged with one of the following statuses:

• PENDING: The delivery is queued
• IN_PROGRESS: The delivery is being attempted
• SUCCESS: The delivery was successful (received 2xx response)
• FAILURE: The delivery failed

Webhooks will be retried up to 3 times with an exponential backoff if your endpoint returns a non-2xx status code. If your endpoint returns a 2xx status code, then the webhook will not be retried.

You can view the delivery status, payload, request, and response details for each webhook attempt in the dashboard.

​

Security

Webhooks are sent over HTTPS and are signed with a secret that is unique to your account. You should:

1. Only use HTTPS endpoints
2. Keep your webhook secret secure and never commit it to version control
3. Always verify the signature of incoming webhooks
4. Contact us immediately if you suspect your webhook secret has been compromised

If you need to rotate your webhook secret, you can delete the existing webhook and create a new one with the same configuration.