Webhooks

Register a webhook endpoint

Register a new webhook endpoint programmatically. Returns the HMAC signing secret ONCE — save it immediately, it cannot be retrieved later. The URL must be HTTPS and is validated against private/internal/cloud-metadata IPs (SSRF protection) with full DNS resolution. Pass verify: true to require a synchronous verification ping (the endpoint must echo a challenge token before registration succeeds). Registration checks organization connector capacity, independently of GET /usage API-call allowance. A quota_check_failed 503 means that capacity could not be established, not that the call allowance is exhausted. The anchor lifecycle callback schemas below retain chain_tx_id and chain_block_height; verification responses instead use network_receipt_id and bitcoin_block.

post/webhooks

Request

  • Base URL: https://app.arkova.ai/api/v1
  • URL: https://app.arkova.ai/api/v1/webhooks
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

urlstring uri required
eventsstring[]
descriptionstring
verifyboolean

Send a verification ping before persisting

scope'self' | 'self_and_descendants'

Delivery scope (SCRUM-3972). 'self' (default) delivers only this organization's own events. 'self_and_descendants' additionally delivers events owned by organizations whose parent is this organization and whose affiliation is APPROVED — one hop, never upward; such cross-organization payloads always carry org_public_id. Additive and nullable-safe per CLAUDE.md §1.8: omitting it preserves the pre-existing behaviour exactly. The cross-organization delivery it enables is behind a server-side gate that is currently OFF, so an endpoint set to 'self_and_descendants' today behaves exactly like 'self'.

Example request

{
  "url": "https://api.example.com/webhooks/arkova",
  "description": "Production HR system"
}

Response

Webhook endpoint registered. Secret returned ONCE.

idstring uuid
urlstring uri
eventsstring[]
is_activeboolean
descriptionstring nullable
scope'self' | 'self_and_descendants'

Delivery scope (SCRUM-3972). 'self' (default) delivers only this organization's own events. 'self_and_descendants' additionally delivers events owned by organizations whose parent is this organization and whose affiliation is APPROVED — one hop, never upward; such cross-organization payloads always carry org_public_id. Additive and nullable-safe per CLAUDE.md §1.8: omitting it preserves the pre-existing behaviour exactly. The cross-organization delivery it enables is behind a server-side gate that is currently OFF, so an endpoint set to 'self_and_descendants' today behaves exactly like 'self'.

created_atstring date-time
updated_atstring date-time
secretstring

64-char hex HMAC-SHA256 signing secret. Save it now — it is shown once.

warningstring

Changes

No recorded changes to this operation across all 1 revision of this API.