Webhooks

Webhooks push submission data to your agent in real time. No polling required.

Events

Event	Trigger
`submission.created`	A human submits a form (complete or partial if `allowPartial` is enabled).
`session.expired`	A session reaches its expiry time without a submission.

Register a webhook

agentsforms webhooks create \
  --url https://your-agent.com/webhook \
  --events submission.created,session.expired

The CLI will generate and display a signing secret. Save it — you’ll need it to verify payloads.

Payload shape

{
  "event": "submission.created",
  "timestamp": "2026-06-23T10:30:00Z",
  "data": {
    "submission_id": "sub_def456",
    "form_id": "form_abc123",
    "session_id": "sess_xyz789",
    "answers": {
      "email": "user@example.com",
      "priority": "high",
      "message": "My billing page is broken"
    },
    "submitted_at": "2026-06-23T10:30:00Z"
  }
}

Verify payloads

Every webhook includes a X-AgentsForms-Signature header:

X-AgentsForms-Signature: sha256=abc123def456...

Verify it with the secret returned at registration time:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = `sha256=${createHmac('sha256', secret).update(payload).digest('hex')}`;
  try {
    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

Retry policy

AgentsForms retries failed deliveries with exponential backoff:

Attempt	Delay
1	immediate
2	30 seconds
3	2 minutes
4	15 minutes
5	1 hour

After 5 failed attempts, the delivery is marked failed. Use the replay endpoint to retry manually.

Idempotency

Webhook deliveries include a X-AgentsForms-Delivery-Id header. Use it to deduplicate — the same delivery may arrive more than once.

List deliveries

agentsforms webhooks deliveries list --webhook-id wh_xxx

Replay a failed delivery

agentsforms webhooks deliveries replay --delivery-id dlv_xxx