Skip to content
AskVault Docs
Try Free →

The Webhooks page

Written by , Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan
Last updated: · 4 min read

Available event types

Conversations & Inbox

  • message.created.
  • conversation.started.
  • conversation.escalated.
  • conversation.resolved.
  • conversation.feedback.

Leads & Revenue

  • lead.captured.
  • lead.qualified.
  • meeting.booked.
  • ecommerce.checkout_recovered.

AI Workflows & Actions

  • agent.action_triggered.
  • agent.action_failed.

System & Voice

  • call.ended.
  • knowledge.gap_detected.
  • knowledge.sync_failed.
  • knowledge.sync_completed.

Creating an endpoint

  1. Dashboard > Webhooks > Create.
  2. Enter URL (e.g., https://yourapp.co/askvault-webhook).
  3. Pick events to subscribe.
  4. Copy the signing secret for HMAC verification.
  5. Click Save.

Verification check fires within 60 seconds.

Payload format

Standard JSON:

{
  "event": "lead.captured",
  "timestamp": "2026-05-15T10:30:00Z",
  "workspace_id": "ws_xxx",
  "data": { ... }
}

See webhooks reference for per-event payloads.

Signature verification

Every signed request carries two headers:

X-AskVault-Signature: sha256=abc123...
X-AskVault-Timestamp: 1715789432

The signature is an HMAC-SHA256 digest of {timestamp}.{raw_body} computed with your signing secret. Verify using the signing secret to confirm authenticity. Detailed verification at webhooks reference.

Retry behavior

If your endpoint returns a 5xx response, times out, or the connection fails:

  • Up to 3 total attempts, with exponential backoff between them (capped at 30 seconds).
  • 4xx responses (other than 410) are treated as a permanent client error and are not retried.
  • 410 Gone stops delivery immediately — it signals your endpoint no longer wants this event.
  • After the final attempt fails: the delivery is logged as failed. There's no automatic pause of the endpoint — replay a failed delivery manually from the Delivery Logs tab, or fix the endpoint and wait for the next matching event.

Delivery log

For each endpoint:

  • Up to 100 most recent deliveries visible per page.
  • Per-delivery status (success / retry / failed).
  • Replay specific deliveries for testing.

Useful for debugging integration issues.

Concurrent deliveries

For high-volume workspaces:

  • Each matching endpoint gets its own delivery, dispatched in the background so a slow endpoint doesn't block the others or your live conversation traffic.
  • A slow-responding endpoint eats into its own delivery timeout rather than throttling other endpoints.

Limits

  • Endpoints per workspace. No plan-based cap enforced today.
  • Event types per endpoint. All or a subset.
  • Payload size. Up to 256 KB.
  • Delivery timeout. 10 seconds; longer fails.

Common pitfalls

Signature verification fails. Wrong secret or wrong hash algorithm. Use HMAC-SHA256.

Endpoint timeout. Your endpoint takes more than 10 seconds. Optimize or use async processing.

Endpoint returns a 4xx. AskVault treats any 4xx other than 410 as a permanent error and does not retry it — fix the root cause (auth, payload shape) rather than waiting for a retry that won't come.

FAQ

Can I have multiple endpoints?

Yes. Each event type can fanout to multiple endpoints.

Will my endpoint receive duplicates?

Rare but possible during network issues. Implement idempotency via the X-AskVault-Delivery header.

What's the latency?

Typically under 30 seconds from event to delivery.

Was this page helpful?