Skip to navigation
API ReferenceWebhooks

Verify a webhook receiver

Verify a webhook receiver.

Credential: Partner secret

Before you call

  • A server-side partner secret for the owning partner. Do not send an Origin header.
  • An active integration that your partner credential permits.
  • Set an Idempotency-Key and reuse it for an identical retry.

Queue a signed synthetic challenge; 202 is not delivery success

Return the exact challenge after checking the signature. Endpoint changes before an unsent test cancel it with ENDPOINT_OR_PAYLOAD_UNAVAILABLE; changes during a send fail verification with VERIFICATION_CONTEXT_CHANGED. A passed test makes pending_verification active; a disabled endpoint becomes paused and must then be activated. Wrong challenges are final failures.

Server-only partner credential access: a 403 means the integration is unauthorized or inactive. Mutations share 60/min per partner; test and replay allow 5/min each per endpoint, rotation 1/min per endpoint. Only committed changes count; identical idempotent replays within 24 hours do not. A 429 includes retryAfter. Conflict details.kind can include IDEMPOTENCY_CONFLICT, ENDPOINT_DELETED, ENDPOINT_LIMIT, REVISION_CONFLICT, VERIFICATION_REQUIRED, ROTATION_IN_PROGRESS or REPLAY_UNAVAILABLE. Webhook availability depends on environment readiness; confirm it with Sinbad.

Webhook delivery must be available in the selected environment. Confirm readiness with Sinbad.

Errors

StatusCodeWhat to do
400VALIDATION_ERRORCorrect the fields reported in details before retrying.
401UNAUTHENTICATEDCreate a new customer session or use a valid server credential.
403FORBIDDENUse a server credential permitted for this active integration.
404NOT_FOUNDCheck the resource ID. A resource that belongs to someone else also returns 404.
409CONFLICTRead the current state again before you prepare or retry.
429RATE_LIMITEDWait for Retry-After before retrying.
503UPSTREAM_ERRORRetry with backoff; preserve the same idempotency key for a repeated mutation.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

webhookIdstringRequiredformat: "^[A-Za-z0-9_-]{1,128}$"

Headers

Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{8,128}$"

Required on mutations. Same key/body returns safe original results for 24 hours. Signing secrets are never returned again.

Request

This endpoint expects an object.

Response headers

Cache-ControlstringOptional

no-store

Response

Success
deliveryIdstringformat: "^[A-Za-z0-9_-]{1,128}$"
statusenum
Allowed values:
originalDeliveryIdstringOptionalformat: "^[A-Za-z0-9_-]{1,128}$"

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error