Webhooks

Webhooks let you receive real-time notifications when events occur in your Zeplo workspace. Configure webhooks from the dashboard under Settings → Webhooks.

Events

Webhook payload

Zeplo sends a POST request to your endpoint with a JSON body:

{
  "event": {
    "id": "evt_abc123",
    "event": "request.complete"
  },
  "webhook": "wh_def456",
  "data": {
    "type": "request",
    "object": {
      "id": "req_xyz789",
      "queue": "q_abc123",
      "status": "completed",
      "method": "POST",
      "url": "https://your-api.com/webhook",
      "response_status_code": 200,
      "response_time": 145,
      "attempts": 1,
      "created": "2026-02-25T12:00:00Z",
      "completed_at": "2026-02-25T12:00:01Z"
    }
  }
}

Verifying signatures

Webhook deliveries include an X-Zeplo-Signature header that you should verify to ensure the payload came from Zeplo.

Step 1: Extract the signatures

The X-Zeplo-Signature header contains one or more comma-separated signatures (multiple signatures allow for zero-downtime secret rotation):

X-Zeplo-Signature: v1=f03de6f61df6e454f3620c4d6aca17ad072d3f8b...,v1=130dcacb53a94d983a37cf2acba98e805a1c3718...

Step 2: Compute the expected signature

Using the raw request body, compute an HMAC-SHA256 using your webhook secret (found in the dashboard).

Step 3: Compare

If at least one of the provided signatures matches your computed signature, the webhook is authentic.

Example (Node.js)

const crypto = require('crypto')

function verifySignature(secret, body, signatures, version = 'v1') {
  const signature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')

  const expected = `${version}=${signature}`
  return signatures.split(',').includes(expected)
}

Note: Always use constant-time string comparison in production to protect against timing attacks.

Email notifications

In addition to webhooks, you can configure email notifications for failed requests under Settings → Notifications in the dashboard.