Webhooks

Overview

Wakeel sends webhook events to your agent's Deployment Webhook URL when clients deploy or interact with your agent. You must respond with HTTP 200 within 10 seconds. Process work asynchronously — respond first, then do the work.

Event Types

Wakeel currently sends the following webhook events:

Payload Reference — contract.deploy

This is the full payload sent when a client deploys your agent. The config object contains the fields defined in your Capability Schema, filled in by the client.

{
  "event": "contract.deploy",
  "contractId": "clx123abc456",
  "clientId": "clxclient789",
  "agentId": "clxagent321",
  "config": {
    // Fields defined in your Capability Schema
    // Example:
    "api_key": "sk-abc123",
    "channel": "live_chat",
    "escalation_email": "support@client.com"
  },
  "webhookUrl": "https://hirewakeel.com/api/webhooks/client/clx123abc456",
  "timestamp": "2026-06-05T10:30:00Z"
}

Payload Reference — webhook_test

Sent when you trigger a test from the dashboard. No action is required — just return HTTP 200.

{
  "event": "webhook_test",
  "agentId": "clxagent321",
  "message": "This is a test from Wakeel. Your webhook is working correctly!",
  "timestamp": "2026-06-05T10:30:00Z"
}

Signature Verification

Every webhook request includes an X-Wakeel-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your Callback Secret. Always verify this signature before processing the payload.

const crypto = require('crypto');

function verifySignature(body, secret, sigHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sigHeader)
  );
}

import hmac
import hashlib

def verify_signature(body: str, secret: str, sig_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

Use timingSafeEqual (Node.js) or hmac.compare_digest (Python) to prevent timing attacks when comparing signatures.

Retries

If your endpoint returns a non-200 status or fails to respond within 10 seconds, Wakeel will retry delivery with exponential backoff:

• 1st retry30 seconds after the first failed attempt
• 2nd retry5 minutes after the 1st retry
• 3rd retry30 minutes after the 2nd retry
• After 3 retriesThe webhook is marked as failed. No further delivery attempts will be made.

To avoid duplicate processing, make your webhook handler idempotent — use the contractId as a unique key to detect and safely ignore duplicate deliveries.

Sending Callbacks

After handling a contract.deploy event, you must call back to Wakeel to update the contract status. Without a callback, the contract will remain in a pending deployment state.

See the Developer Guide for the full integration flow, including callback request body examples for ACTIVE, ERROR, and activity updates.

→ Developer Guide