Receive and verify AgentLine AI phone agent webhooks using HMAC-SHA256 signature verification for events like calls and SMS.
- GitHub stars
- 101
- Files
- 18
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the agentline-webhooks skill do?
agentline-webhooks is an agent skill. Receive and verify AgentLine AI phone agent webhooks using HMAC-SHA256 signature verification for events like calls and SMS.
Summary generated from the skill's SKILL.md.
About the agentline-webhooks skill
Developers building AI phone agents can use this skill to receive and validate incoming data from AgentLine. It provides the necessary logic to verify X-Webhook-Signature headers using HMAC-SHA256, ensuring that incoming requests are authentic and have not been tampered with. This is particularly useful for developers who need to manually implement verification since no official Node SDK is available.
An agent should load this skill when it needs to process real-time events such as call.received, call.utterance, call.completed, or sms.received. The skill relies on the raw request body and a unique signing secret to perform security checks. It helps manage various telephony triggers, including call failures, busy signals, or when an agent hands a task to its owner. By using the provided patterns, developers can build reliable handlers for live transcripts and conversation state management.
What an agent can do with it
- 1Verify webhook authenticityConfirm that incoming AgentLine requests are legitimate by checking the HMAC-SHA256 signature against the raw request body.
- 2Manage post-call dataAutomatically save call records and retrieve transcripts once a conversation has finished.
- 3Test webhook endpoint connectivityTrigger a test delivery to ensure your webhook URL is correctly wired up and reachable.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the agentline-webhooks skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the agentline-webhooks skill in Claude Code
~/.claude/skills/agentline-webhooks/SKILL.md
$ npx degit hookdeck/webhook-skills/skills/agentline-webhooks ~/.claude/skills/agentline-webhooksInstall the agentline-webhooks skill in Claude Code (project)
.claude/skills/agentline-webhooks/SKILL.md
$ npx degit hookdeck/webhook-skills/skills/agentline-webhooks .claude/skills/agentline-webhooksInstall the agentline-webhooks skill in Codex
~/.agents/skills/agentline-webhooks/SKILL.md
$ npx degit hookdeck/webhook-skills/skills/agentline-webhooks ~/.agents/skills/agentline-webhooksInstall the agentline-webhooks skill in Gemini CLI
~/.gemini/skills/agentline-webhooks/SKILL.md
$ npx degit hookdeck/webhook-skills/skills/agentline-webhooks ~/.gemini/skills/agentline-webhooksInstall the agentline-webhooks skill in Claude.ai
npx degit hookdeck/webhook-skills/skills/agentline-webhooks agentline-webhooks && zip -r agentline-webhooks.zip agentline-webhooks # claude.ai → Customize → Skills → + → Create skill → Upload a skill → agentline-webhooks.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablehookdeck/webhook-skills/skills/agentline-webhooks is public and reachablegithub.com/hookdeck/webhook-skills/tree/HEAD/skills/agentlin ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/hookdeck/webhook-skills/commits ↗Pass
- No download-and-run or credential theft in scripts5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/hookdeck/webhook-skills/blob/HEAD/skills/agentlin ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/hookdeck/webhook-skills/blob/HEAD/skills/agentlin ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 137 linesgithub.com/hookdeck/webhook-skills/blob/HEAD/skills/agentlin ↗Pass
SKILL.md
View on GitHubAgentLine 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.utteranceorsms.receivedevents? - 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
| Event | Triggered When | Common Use Cases |
|---|---|---|
call.received |
An inbound call is answered | Log the caller, start a session |
call.utterance |
A live caller turn (conversation uses user / assistant roles) |
Live transcripts, real-time reply logic |
call.completed |
A call finishes | Persist the call record, fetch the transcript |
call.owner_task |
The agent hands a task to its owner | Create a follow-up task |
call.failed |
A call fails | Alerting, retry |
call.busy |
The callee line was busy | Schedule a retry |
call.no-answer |
The callee did not answer | Schedule a retry |
call.canceled |
A call was canceled | Clean up state |
sms.received |
An inbound SMS arrives | Conversation handling |
webhook.test |
You trigger a test delivery | Confirm 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
- 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
Files in this skill
18agentline-webhooks skill questions
How do I install the agentline-webhooks skill in Claude Code?
Run npx degit hookdeck/webhook-skills/skills/agentline-webhooks ~/.claude/skills/agentline-webhooks. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the agentline-webhooks skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What event types does AgentLine support?
Supported events include call.received, call.utterance, call.completed, call.owner_task, call.failed, call.busy, call.no-answer, call.canceled, sms.received, and webhook.test.