Skip to navigation
API ReferenceWebhooks

Register a webhook endpoint

Register a webhook endpoint.

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.

Register pending verification; store the returned signing secret securely

Use a public HTTPS hostname with port 443, no credentials, query, fragment, IP literal, trailing dot or reserved local/internal/test hostname. DNS must resolve only to public addresses and is checked again on delivery. Redirects are not followed. Invalid URL syntax returns 400; failed DNS resolution or a non-public resolved address currently returns 503 UPSTREAM_ERROR. Maximum five live endpoints per partner (409 ENDPOINT_LIMIT).

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.

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.
integrationIdstringRequiredformat: "^[A-Za-z0-9_-]{1,128}$"
urlstringRequiredformat: "uri"<=2048 characters
eventTypeslist of enumsRequired
Allowed values:
descriptionstringOptional<=200 charactersDefaults to

Response headers

Cache-ControlstringOptional

no-store

Response

Success
webhookobjectOptional
webhookIdstringOptionalformat: "^[A-Za-z0-9_-]{1,128}$"
signingSecretstringOptional
signingKeyIdstringOptionalformat: "^[A-Za-z0-9_-]{1,128}$"
secretReturnedbooleanOptional

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