CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

agentline-webhooks

Receive and verify AgentLine webhooks. Use when setting up AgentLine (AI phone agent) webhook handlers, debugging X-Webhook-Signature verification, or handling events like call.received, call.utterance, call.completed and sms.received.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/agentline-webhooks/SKILL.md
SKILL.md
Quality
Evals
Security

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:

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'));
}
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

EventTriggered WhenCommon Use Cases
call.receivedAn inbound call is answeredLog the caller, start a session
call.utteranceA live caller turn (conversation uses user / assistant roles)Live transcripts, real-time reply logic
call.completedA call finishesPersist the call record, fetch the transcript
call.owner_taskThe agent hands a task to its ownerCreate a follow-up task
call.failedA call failsAlerting, retry
call.busyThe callee line was busySchedule a retry
call.no-answerThe callee did not answerSchedule a retry
call.canceledA call was canceledClean up state
sms.receivedAn inbound SMS arrivesConversation handling
webhook.testYou trigger a test deliveryConfirm the endpoint is wired up

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

# 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:

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

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):

Related Skills

Repository

hookdeck/webhook-skills

Path

skills/agentline-webhooks/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.