User Webhooks

Webhooks let you receive HTTP POST notifications whenever key events occur in your AskVerdict account — such as when a debate finishes or an outcome is recorded. Each delivery is signed with HMAC-SHA256 so you can verify requests are authentic.

Webhook Events

When creating or updating a webhook, you subscribe to one or more of the following events:

Payload Signature Verification

Every webhook delivery includes an X-Verdict-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook's secret.

import { createHmac } from "crypto";
 
function verifySignature(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return expected === signature;
}
 
// In your webhook handler:
const sig = req.headers["x-verdict-signature"];
const body = await req.text(); // raw body before parsing
if (!verifySignature(body, sig, process.env.WEBHOOK_SECRET)) {
  return new Response("Unauthorized", { status: 401 });
}

Endpoints

List Webhooks

No request body or query parameters required.

Create Webhook

curl -X POST https://api.askverdict.ai/api/webhooks \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.example.com/hooks/askverdict",
    "events": ["debate.completed", "debate.failed"],
    "description": "Production webhook"
  }'

Error Responses

Update Webhook

Path Parameters

All body fields are optional. Only supplied fields are updated.

curl -X PUT https://api.askverdict.ai/api/webhooks/wh_abc123def456 \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["debate.completed", "outcome.recorded", "outcome.updated"],
    "active": true
  }'

Error Responses

Delete Webhook

Path Parameters

Delivery History

List Deliveries

Path Parameters

Query Parameters

curl "https://api.askverdict.ai/api/webhooks/wh_abc123def456/deliveries?limit=20&offset=0" \
  -H "Authorization: Bearer vrd_your_api_key"

Redeliver a Delivery

This is useful for re-processing a failed delivery or replaying a specific event after fixing your endpoint.

Path Parameters

No request body required.

curl -X POST \
  "https://api.askverdict.ai/api/webhooks/wh_abc123def456/deliveries/del_uvw321/redeliver" \
  -H "Authorization: Bearer vrd_your_api_key"

The deliveryId in the response is the ID of the newly queued attempt. Poll the deliveries list to check its outcome.

Error Responses

Send Test Ping

The test ping sends a ping event with a minimal payload. It is recorded in your delivery history like any other delivery.

Path Parameters

No request body required.

curl -X POST https://api.askverdict.ai/api/webhooks/wh_abc123def456/test \
  -H "Authorization: Bearer vrd_your_api_key"

Error Responses