Webhook Endpoints

Create and manage webhook subscriptions programmatically so your systems hear about each settlement the moment it occurs. The list of events and the payload structure are documented in Real-Time Event Stream.

Create a subscription

POST /v1/webhooks

Body

{
  "url": "https://yourapp.com/hooks/cyphron",
  "events": ["transfer.confirmed", "agent.transaction.pending_approval"]
}

Response

{
  "webhook_id": "wh_2c9f1a",
  "url": "https://yourapp.com/hooks/cyphron",
  "events": ["transfer.confirmed", "agent.transaction.pending_approval"],
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-07-02T09:00:00Z"
}

You will only see the secret in this response. Use it to check the X-Cyphron-Signature header on incoming deliveries.

List subscriptions

GET /v1/webhooks

Delete a subscription

DELETE /v1/webhooks/{webhook_id}

Deletion is immediate, and the subscription receives no more deliveries.

Checking signatures

Each delivery includes an X-Cyphron-Signature header containing an HMAC-SHA256 of the raw request body, computed with your secret. Verification needs only a short function:

import hmac
import hashlib

def verify_signature(payload_bytes, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

If a delivery doesn't pass this check, discard it without processing it.

Resend an event

POST /v1/webhooks/{webhook_id}/replay/{event_id}

Useful when your endpoint had a short outage and you want a particular event delivered now instead of waiting for the next automatic retry.

View delivery history

GET /v1/webhooks/{webhook_id}/deliveries

Shows a subscription's recent deliveries, including response codes and retry counts, so you can troubleshoot from the complete record instead of guessing.