Webhooks API¶

Programmatically manage webhook endpoints and view event history.

Endpoints Overview¶

Endpoint	Method	Description
`/webhooks/endpoints`	POST	Create webhook endpoint
`/webhooks/endpoints`	GET	List webhook endpoints
`/webhooks/endpoints/{id}`	GET	Get endpoint details
`/webhooks/endpoints/{id}`	PATCH	Update endpoint
`/webhooks/endpoints/{id}`	DELETE	Delete endpoint
`/webhooks/endpoints/{id}/rotate-secret`	POST	Rotate signing secret
`/webhooks/endpoints/{id}/test`	POST	Send test webhook
`/webhooks/events`	GET	List webhook events
`/webhooks/events/{id}`	GET	Get event details
`/webhooks/deliveries`	GET	List delivery attempts
`/webhooks/event-types`	GET	List available event types

Authentication¶

All endpoints require authentication via X-API-Key header or JWT Bearer token.

Create Webhook Endpoint¶

POST /webhooks/endpoints

Request Body¶

{
  "url": "https://your-app.com/webhooks/circuit",
  "events": ["identity.created", "identity.verified"],
  "description": "Production webhook endpoint"
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhooks (localhost allowed for testing)
`events`	array	No	Event types to subscribe to (all if empty)
`description`	string	No	Human-readable description

Response¶

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/circuit",
  "description": "Production webhook endpoint",
  "events": ["identity.created", "identity.verified"],
  "is_active": true,
  "secret": "whsec_xyz789...",
  "created_at": "2024-01-15T10:30:00Z"
}

Save Your Secret

The signing secret is only returned once when creating the endpoint. Store it securely.

List Webhook Endpoints¶

GET /webhooks/endpoints

Response¶

[
  {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks/circuit",
    "description": "Production webhook",
    "events": ["identity.created", "identity.verified"],
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Update Webhook Endpoint¶

PATCH /webhooks/endpoints/{endpoint_id}

Request Body¶

{
  "url": "https://new-url.com/webhooks",
  "events": ["identity.created", "identity.verified", "verification.completed"],
  "is_active": false
}

All fields are optional. Only provided fields will be updated.

Delete Webhook Endpoint¶

DELETE /webhooks/endpoints/{endpoint_id}

Response¶

{
  "deleted": true
}

Rotate Signing Secret¶

POST /webhooks/endpoints/{endpoint_id}/rotate-secret

Generates a new signing secret. The old secret stops working immediately.

Response¶

{
  "id": "wh_abc123",
  "new_secret": "whsec_new_secret_here..."
}

Send Test Webhook¶

POST /webhooks/endpoints/{endpoint_id}/test

Request Body¶

{
  "event_type": "identity.created"
}

Response¶

Returns the created test event with delivery status:

{
  "id": "evt_test123",
  "event_type": "identity.created",
  "event_data": {
    "test": true,
    "identity_id": "test_id_123",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "deliveries": [
    {
      "id": "del_xyz789",
      "status": "delivered",
      "attempt_count": 1,
      "response_status": 200,
      "delivered_at": "2024-01-15T10:30:01Z"
    }
  ]
}

List Webhook Events¶

GET /webhooks/events?limit=50&offset=0

Query Parameters¶

Parameter	Type	Default	Description
`limit`	integer	50	Max events to return (1-100)
`offset`	integer	0	Pagination offset

List Deliveries¶

GET /webhooks/deliveries?endpoint_id={id}&status=failed&limit=50

Query Parameters¶

Parameter	Type	Default	Description
`endpoint_id`	string	-	Filter by endpoint
`status`	string	-	Filter by status: `pending`, `delivered`, `failed`
`limit`	integer	50	Max deliveries to return
`offset`	integer	0	Pagination offset

List Event Types¶

GET /webhooks/event-types

Returns all available event types:

{
  "event_types": [
    {
      "type": "identity.created",
      "description": "A new identity has been created",
      "category": "identity"
    },
    {
      "type": "identity.verified",
      "description": "An identity has been verified",
      "category": "identity"
    },
    {
      "type": "verification.completed",
      "description": "A verification check completed successfully",
      "category": "verification"
    }
  ]
}

Webhook Delivery¶

When an event occurs, Circuit sends a POST request to your endpoint:

Headers¶

Header	Description
`Content-Type`	`application/json`
`X-Circuit-Signature`	HMAC-SHA256 signature
`X-Circuit-Timestamp`	Unix timestamp when sent
`X-Circuit-Event-ID`	Unique event ID
`X-Circuit-Event-Type`	Event type (e.g., `identity.created`)

Body¶

{
  "id": "evt_abc123",
  "event_type": "identity.verified",
  "created_at": "2024-01-15T10:30:00Z",
  "event_data": {
    "identity_id": "id_xyz789",
    "kyc_level": "enhanced",
    "confidence_score": 0.95
  }
}

Retry Policy¶

Failed deliveries are retried with exponential backoff:

Attempt 1: Immediate
Attempt 2: 1 minute
Attempt 3: 5 minutes
Attempt 4: 30 minutes
Attempt 5: 2 hours

After 5 failed attempts, the delivery is marked as failed.

Signature Verification¶

See Webhook Security Guide for implementation details.