Partner APIWebhooks

Create a partner-level webhook endpoint

Registers a partner-level webhook endpoint that receives events for all organizations under your partner account (each event carries its org_id and the candidate’s external_ref). The response includes the signing secret (cfwh_...) — shown once.

Authentication

AuthorizationBearer
Partner API key sent as `Authorization: Bearer cfk_...`. Keys are partner-level — one key reaches every registry linked to your partner account and nothing else. CONFIRM issues and revokes them; a key is shown exactly once at creation because only its hash is stored, and revocation takes effect on the next request. Develop against the sandbox base URL with a sandbox key, where telephony is restricted to an allowlist you provide.

Headers

Idempotency-KeystringOptional<=255 characters

Unique key (e.g. a UUID) making this POST safe to retry. Replays within 24 hours return the original response without repeating side effects.

Request

This endpoint expects an object.
urlstringRequiredformat: "uri"
HTTPS URL deliveries are POSTed to.
eventslist of stringsRequired

Event types to subscribe to, or ["*"] for all.

descriptionstring or nullOptional

Response

Webhook endpoint created; secret is shown only in this response.

idstringOptional

Webhook endpoint ID (whk_...).

org_idstring or nullOptional

Owning organization, or null for a partner-level endpoint receiving events for all organizations.

urlstringOptionalformat: "uri"
eventslist of stringsOptional

Subscribed event types, or ["*"].

descriptionstring or nullOptional
secretstring or nullOptional

Signing secret (cfwh_...) used for the Confirm-Signature HMAC-SHA256 header. Returned only in the create response; null everywhere else.

created_atdatetimeOptional

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error