Agent API/Webhooks

Webhook Events

Webhooks are outbound — AskHandle calls YOUR server, not the other way around. Open Tools → Integrations & Actions, choose HTTP, pick When events, and enter your endpoint URL. AskHandle will POST a JSON payload when those events fire. You can also set an optional signing secret so your server can verify that requests genuinely come from AskHandle.

POST

https://{your-server.com}/webhook

Signed with X-Webhook-Signature — Set a signing secret in Tools → Integrations & Actions → HTTP. AskHandle will include an X-Webhook-Signature: sha256=<hex> header so your server can verify the request. See code examples for how to validate it.

Payload AskHandle sends to your server

Headers

Content-Type

stringrequired

application/json

X-Webhook-Event

stringrequired

X-Webhook-Timestamp

stringrequired

ISO timestamp of when the event occurred

X-Webhook-Signature

string

sha256=<HMAC-SHA256 hex> — only present when a signing secret is configured

User-Agent

stringrequired

AskHandle-Webhook/1.0

Body

JSON payload with event details

JSON

{
  "event": "lead.captured",
  "timestamp": "2026-03-21T10:06:00.000Z",
  "workflowId": "wf_xyz789",
  "workflowName": "Sales Bot",
  "data": {
    "leadId": "cm1abc123def456",
    "sender": "session_a1b2c3",
    "channel": "web",
    "messageCount": 8,
    "startedAt": "2026-03-21T10:00:00.000Z",
    "endedAt": "2026-03-21T10:05:00.000Z",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "phone": "+14155552671",
    "company": "Acme Inc",
    "jobTitle": "CTO",
    "budget": "$50k",
    "timeline": "Q2 2026",
    "interest": "high",
    "notes": null,
    "customFields": {
      "industry": "SaaS"
    },
    "formResponses": null
  }
}

Response

Success 200

JSON

{}

Errors

400

Your endpoint returned a 4xx response. AskHandle will NOT retry 4xx errors.

Error

{}

500

Your endpoint returned a 5xx response. AskHandle retries up to 3 times with exponential back-off (1 s, 2 s, 4 s).

Error

{}

Code examples

// Express.js webhook receiver with signature verification
import crypto from 'crypto';
import express from 'express';

const app = express();

// IMPORTANT: use raw body for signature verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.WEBHOOK_SECRET;
  const signature = req.headers['x-webhook-signature'];

  if (secret && signature) {
    const expected = 'sha256=' + crypto
      .createHmac('sha256', secret)
      .update(req.body)
      .digest('hex');

    if (signature !== expected) {
      return res.status(401).send('Invalid signature');
    }
  }

  const event = JSON.parse(req.body);
  console.log('Event:', event.event);

  if (event.event === 'lead.captured') {
    const lead = event.data;
    console.log(`New lead: ${lead.firstName} ${lead.lastName} — ${lead.email}`);
    // Sync to your CRM, database, etc.
  }

  res.status(200).send('OK');
});

Payload AskHandle sends to your server

Headers

Content-Type

stringrequired

application/json

X-Webhook-Event

stringrequired

X-Webhook-Timestamp

stringrequired

ISO timestamp of when the event occurred

X-Webhook-Signature

string

sha256=<HMAC-SHA256 hex> — only present when a signing secret is configured

User-Agent

stringrequired

AskHandle-Webhook/1.0

Body

JSON payload with event details

JSON

{
  "event": "lead.captured",
  "timestamp": "2026-03-21T10:06:00.000Z",
  "workflowId": "wf_xyz789",
  "workflowName": "Sales Bot",
  "data": {
    "leadId": "cm1abc123def456",
    "sender": "session_a1b2c3",
    "channel": "web",
    "messageCount": 8,
    "startedAt": "2026-03-21T10:00:00.000Z",
    "endedAt": "2026-03-21T10:05:00.000Z",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "phone": "+14155552671",
    "company": "Acme Inc",
    "jobTitle": "CTO",
    "budget": "$50k",
    "timeline": "Q2 2026",
    "interest": "high",
    "notes": null,
    "customFields": {
      "industry": "SaaS"
    },
    "formResponses": null
  }
}

// Express.js webhook receiver with signature verification import crypto from 'crypto'; import express from 'express'; const app = express(); // IMPORTANT: use raw body for signature verification app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { const secret = process.env.WEBHOOK_SECRET; const signature = req.headers['x-webhook-signature']; if (secret && signature) { const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(req.body) .digest('hex'); if (signature !== expected) { return res.status(401).send('Invalid signature'); } } const event = JSON.parse(req.body); console.log('Event:', event.event); if (event.event === 'lead.captured') { const lead = event.data; console.log(`New lead: ${lead.firstName} ${lead.lastName} — ${lead.email}`); // Sync to your CRM, database, etc. } res.status(200).send('OK'); });