Webhooks

Overview

Webhooks let you receive HTTP POST notifications when events happen — like a case completing or a decision requiring human review. Instead of polling the API, your server gets notified immediately.

Create Webhook

POST /api/v1/webhooks
Authorization: Bearer aira_live_xxxxx

Request Body

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive events
`events`	string[]	No	Event types to subscribe to (default: all)

Available Events

Event	Triggered When
`case.complete`	A case finishes successfully
`case.requires_human_review`	A case's disagreement score exceeds the human review threshold

Example Request

curl -X POST https://api.airaproof.com/api/v1/webhooks \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.acme.com/webhooks/aira",
    "events": ["case.complete", "case.requires_human_review"]
  }'

Response (201 Created)

{
  "id": "wh_01J8X...",
  "url": "https://app.acme.com/webhooks/aira",
  "secret": "whsec_a1b2c3d4e5f6...",
  "events": ["case.complete", "case.requires_human_review"],
  "status": "active",
  "created_at": "2026-03-14T10:30:00Z",
  "request_id": "req_01J8X..."
}

The secret is only returned once, at creation time. Copy it immediately — you'll need it to verify webhook signatures. It will not appear in subsequent API responses.

List Webhooks

GET /api/v1/webhooks
Authorization: Bearer aira_live_xxxxx

Returns all webhooks for your organization. The secret field is always null in list responses.

Example Response

[
  {
    "id": "wh_01J8X...",
    "url": "https://app.acme.com/webhooks/aira",
    "secret": null,
    "events": ["case.complete", "case.requires_human_review"],
    "status": "active",
    "created_at": "2026-03-14T10:30:00Z",
    "request_id": "req_..."
  }
]

Delete Webhook

DELETE /api/v1/webhooks/{id}
Authorization: Bearer aira_live_xxxxx

Removes the webhook. No further events will be delivered. Returns 204 No Content.

Delivery Log

GET /api/v1/webhooks/{id}/deliveries?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated log of all delivery attempts for a webhook.

Example Response

{
  "data": [
    {
      "id": "dlv_01J8X...",
      "event": "case.complete",
      "payload": { "case_id": "prn_01J8X...", "decision": "APPROVE" },
      "status_code": 200,
      "attempt": 1,
      "status": "delivered",
      "delivered_at": "2026-03-14T10:31:00Z",
      "created_at": "2026-03-14T10:30:59Z"
    },
    {
      "id": "dlv_02K9Y...",
      "event": "case.complete",
      "payload": { "case_id": "prn_02K9Y...", "decision": "DENY" },
      "status_code": null,
      "attempt": 3,
      "status": "failed",
      "delivered_at": null,
      "created_at": "2026-03-14T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "has_more": true
  },
  "request_id": "req_..."
}

Delivery Fields

Field	Type	Description
`event`	string	The event type that triggered this delivery
`payload`	object	The event payload sent to your endpoint
`status_code`	integer\|null	HTTP status code from your endpoint (null if unreachable)
`attempt`	integer	Delivery attempt number (retries increment this)
`status`	string	`delivered`, `failed`, or `pending`
`delivered_at`	string\|null	When your endpoint acknowledged the delivery

Webhook Payloads

All webhook payloads are sent as JSON via HTTP POST:

POST https://your-url.com/webhooks/aira
Content-Type: application/json

`case.complete`

Sent when a case case completes:

{
  "event": "case.complete",
  "case_id": "prn_01J8X...",
  "decision": "APPROVE",
  "confidence_score": 0.85,
  "disagreement_score": 0.28,
  "requires_human_review": false,
  "receipt_id": "rct_01J8X...",
  "timestamp": "2026-03-14T10:30:59Z"
}

`case.requires_human_review`

Sent when a case flags a decision for human review:

{
  "event": "case.requires_human_review",
  "case_id": "prn_01J8X...",
  "decision": "MIXED",
  "confidence_score": 0.45,
  "disagreement_score": 0.72,
  "human_review_reason": "Disagreement score 0.72 exceeds threshold 0.30",
  "receipt_id": "rct_01J8X...",
  "timestamp": "2026-03-14T10:30:59Z"
}

On this page