Skip to main content

Assessor.io API v2 (public) - Webhook Subscriptions

Manage the account's outbound webhook subscriptions. All four operations take the single scope webhooks:manage. The signing secret is write-only: it is accepted on create and never returned by any read. If it is lost, delete the subscription and register a new one. Delivery behaviour, for the receiver you register: Assessor.io POSTs application/json with a body carrying three properties - event, accountId, and payload - plus an X-Assessor-Event header carrying the event type, and - when the subscription has a secret - an X-Assessor-Signature header holding 'sha256=' followed by the hex HMAC-SHA256 of the exact raw body. Verify against the raw bytes, not a re-serialised object. Any 2xx counts as accepted; anything else is retried, up to 3 attempts in all, waiting at least 1 minute and then 2 minutes between them, after which the subscription's deliveryFailureCount is incremented. Deliveries are queued, then drained by a scheduled processor, so they are near-real-time rather than synchronous. Event names come from a CLOSED server-side catalogue (WEBHOOK_EVENT_TYPES; the "Event types" table in the v2 integration guide is the whole of it). A name outside it is refused with a 400 that names it; it used to be accepted and then silently never fire. Three of the catalogue's names are delivered AFTER their database transaction commits, because the rows behind them are written beside an audit record: registration.accepted, communication.created and communication.dispatch.queued. On the wire they are identical to every other event. The one consequence: if the delivery queue cannot be reached at that moment the write still stands and nothing is queued for it, so treat those three as at-most-once and reconcile against the resource if you need certainty.

Getting a token, the scopes and the response envelope are explained in Make your first API call and Public API (v2).

Contract Summary​

  • Version: 1.0.1
  • Visibility: public
  • Operations: 4
  • Tags: PublicWebhooks

Operations​

MethodPathSummaryOperation ID
GET/api/v2/public/accounts/{accountId}/webhooksList the account's webhook subscriptions.v2ListWebhookSubscriptions
POST/api/v2/public/accounts/{accountId}/webhooksRegister a webhook subscription.v2CreateWebhookSubscription
PATCH/api/v2/public/accounts/{accountId}/webhooks/{subscriptionId}Activate or deactivate a subscription.v2SetWebhookSubscriptionActive
DELETE/api/v2/public/accounts/{accountId}/webhooks/{subscriptionId}Unsubscribe.v2DeleteWebhookSubscription

Raw Contract​