Create a webhook
Register a destination to receive selected events from your company.
Register a receiving URL and select the events your integration needs to
follow. Keep the returned secret in a private application environment:
configuration queries do not return this value. If the receiver is not
ready yet, register it with is_active: false.
See Register a destination and Receive and validate events before starting to receive notifications.
Headers
Unique key chosen by your system to identify this request. When retrying, send the same key and parameters. Without this header, the request is processed normally. See the idempotency guide for retention and handling pending or uncertain responses.
1 to 255 characters
Body Params
Applying an example replaces the body fields.
Name to identify the destination.
1 to 25 characters
HTTPS URL that receives events. Use the default port 443 and a public address outside Raims.
1 to 512 characters
Codes of the events this destination should receive. Query the available event catalog.
Defines whether the destination can receive events after creation.
Responses
Response Body
Webhook created. Store the returned signing secret.
Created webhook and the secret required to validate its signatures.
Public webhook identifier.
Name used to identify the destination.
HTTPS URL registered to receive events.
Codes of the events subscribed to by this destination.
Indicates whether the webhook is active to receive events.
Reason for deactivation: manual for a customer action; continuous_failure may appear in webhooks previously deactivated because of failures. Returns null when the webhook is active.
Deactivation time, in UTC Unix seconds, or null when the webhook is active or this date was not recorded.
Expiry time of the previous secret, in UTC Unix seconds, or null when no transition is active.
Registration time, in UTC Unix seconds.
Time of the last webhook configuration change, in UTC Unix seconds.
Secret used to validate event signatures. Store it securely; queries of the webhook configuration do not return it.
Indicates whether deliveries are waiting to resume. The original delivery deadline continues to run while paused.
Start of the current pause, in UTC Unix seconds, or null when deliveries are not paused.
Response Body
A field, filter or identifier is invalid. Check the details before repeating the request.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
Creation encountered a limit or an existing configuration. Check the reported condition before repeating the request.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
For common errors, see HTTP response codes.