Agentline Webhooks

AgentLine Webhooks

When to Use This Skill

• How do I receive AgentLine webhooks?
• How do I verify AgentLine webhook signatures (X-Webhook-Signature)?
• How do I handle call.completed, call.utterance or sms.received events?
• Why is my AgentLine webhook signature verification failing?
• How do I test an AgentLine webhook with webhook.test?

Verification (core)

AgentLine signs the raw request body with HMAC-SHA256, keyed with the webhook signing secret as a UTF-8 string, and sends the bare hex digest (no prefix, no timestamp) in the X-Webhook-Signature header. The secret is returned in full once when the webhook is created and is masked on later reads. Always verify against the raw body, never re-serialized JSON.

AgentLine has no published webhook SDK for Node (the Node package is not on npm), so verify manually:

javascriptCopy code
const crypto = require('crypto');

function verifyAgentLineSignature(rawBody, signature, secret) {
  // Check shape first: Buffer.from(x, 'hex') silently truncates invalid hex
  if (!/^[0-9a-f]{64}$/i.test(signature || '')) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

pythonCopy code
import hashlib, hmac

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    # Compare bytes so a non-ASCII header returns False (401), not a TypeError (500)
    return hmac.compare_digest(expected.encode(), signature.lower().encode())

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

Each agent has one webhook URL that receives all of its events. Event objects in AgentLine's events API have the shape { event_id, agent_id, event_type, payload, created_at }; the docs do not publish the exact HTTP delivery envelope, so the examples read the type from event_type (falling back to type / event). Log a real webhook.test delivery to confirm. See references/overview.md.

Environment Variables

bashCopy code
# Signing secret returned once when the webhook was created
AGENTLINE_WEBHOOK_SECRET=your_webhook_signing_secret
PORT=3000

Setup

Create the webhook with POST /v1/webhooks (agent_id, url, optional secret), save the returned secret, and keep the default X-Webhook-Signature header. AgentLine allows a custom signature_header, but Hookdeck's AgentLine source only checks X-Webhook-Signature, so a custom header is not supported. Details: references/setup.md.

Local Development

For local webhook testing, run the Hookdeck CLI via npx — no install required:

bashCopy code
npx hookdeck-cli listen 3000 agentline --path /webhooks/agentline

No account required — the CLI creates a guest account on first run and provides a local tunnel + web UI for inspecting requests. Express and Next.js examples use port 3000; the FastAPI example uses 8000.

Resources

• Overview - What AgentLine webhooks are, event types
• Setup - Create the webhook, get the signing secret
• Verification - Signature details and gotchas
• Express Example - Express.js implementation
• Next.js Example - Next.js App Router implementation
• FastAPI Example - Python FastAPI implementation

Recommended: webhook-handler-patterns

We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):

• Handler sequence — Verify first, parse second, handle idempotently third
• Idempotency — Dedupe deliveries
• Error handling — Return codes, logging, dead letter queues
• Retry logic — Provider retry schedules, backoff patterns

Related Skills

• retell-webhooks - Retell AI voice agent webhooks
• vapi-webhooks - Vapi voice agent webhooks
• bland-ai-webhooks - Bland AI phone call webhooks
• elevenlabs-webhooks - ElevenLabs conversational AI webhooks
• twilio-webhooks - Twilio voice and SMS webhooks
• telnyx-webhooks - Telnyx telephony webhooks
• openclaw-webhooks - OpenClaw agent webhooks
• github-webhooks - GitHub webhooks (simple HMAC-SHA256 hex)
• webhook-handler-patterns - Handler sequence, idempotency, error handling, retry logic
• hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers