Skip to main content

Create a new webhook​

Create a new webhook for your organization. Webhooks will be called in response to triggers, and you can use the /organizations/webhooks/{webhook_id}/triggers endpoint to specify which trigger(s) should call each webhook.

The request body must contain the target URL for the webhook, and this must be unique for your organization (you cannot have two webhooks with the same target URL). The target URL must use the HTTPS protocol, and must have a host. The host cannot be localhost or an IP address. The target URL may have a path element, but may not contain query parameters or fragments.

Additionally, you can specify custom headers that will be sent in the HTTP header of each request to your webhook's target URL. These are encrypted when stored, so can be used for sensitive data.

You can also choose the webhook's timeout value. This will determine how long your webhook server has to respond to a request before it is considered failed. If you do not set a value, defaults will be used: for synchronous webhook calls, this is 2 seconds; for asynchronous calls, 10 seconds. When choosing a timeout, you should consider how long your webhook will typically need to process a request, and how this may affect user experience (in the case of sychronous webhooks). The value provided should be a string that can be parsed as a Golang time.Duration; for example, "10s", "500ms". The timeout may not be more than 20 seconds, and cannot be negative. If you do not set a timeout, when retrieving the webhook you will see a timeout set to 0s, indicating that the defaults will be used when the webhook is called.

You may also specify a name and description for the webhook.

The response will contain a webhook ID, which uniquely identifies the newly created webhook. This ID can be used to modify or delete the webhook, and to add triggers for it.

For more information on using webhooks with SlashID, see our dedicated guide.

Header Parameters
  • SlashID-OrgID string required

    The organization ID

    Example: af5fbd30-7ce7-4548-8b30-4cd59cb2aba1
  • SlashID-Required-Consistency string

    Possible values: [local_region, all_regions]

    Default value: local_region

    The consistency level required for this request. If the consistency level is not achieved within the timeout, the request will fail with a 408 Request Timeout error. 408 Request Timeout error indicates that request was not handled within the timeout, but it may still be handled after request timeout. Allowed values: * local_region: Wait while the request executes in the local region. * all_regions: Wait while the request executes across all regions. You can learn more about our replication model on our Cross-region Replication Model page.

  • SlashID-Required-Consistency-Timeout integer

    Possible values: >= 1 and <= 120

    Default value: 30

    The maximum amount of seconds to wait for the requested consistency level to be achieved. If the consistency level is not achieved within this time, the request will fail with a 408 Request Timeout error. 408 Request Timeout error indicates that request was not handled within the timeout, but it may still be handled after request timeout. You can learn more about our replication model on our Cross-region Replication Model page.

Request Body required
  • name string required

    Human-readable name for this webhook. This does not need to be unique, but it is recommended that you choose a name that can be used to distinguish this webhook from others.

  • description string

    A description of this webhook. This can be used to associate additional information with this webhook for future reference.

  • target_url string required

    The target URL for this webhook. This URL must include the protocol, and the protocol must be HTTPS. A target URL can be registered at most once per organization, but each target URL can have multiple triggers.

  • custom_headers object

    A set of custom HTTP headers that will be included in requests to this webhook, provided as key-value pairs.

  • type
  • items string
  • timeout string

    The timeout that will be applied when calling this webhook.

Responses

Created

Schema
  • meta object
  • pagination object
  • limit integer
  • offset integer
  • total_count int64
  • errors object[]
  • httpcode integer
  • message string
  • result object
  • id string
  • name string

    Human-readable name for this webhook. This does not need to be unique, but it is recommended that you choose a name that can be used to distinguish this webhook from others.

  • description string

    A description of this webhook. This can be used to associate additional information with this webhook for future reference.

  • target_url string

    The target URL for this webhook. This URL must include the protocol, and the protocol must be HTTPS. A target URL can be registered at most once per organization, but each target URL can have multiple triggers.

  • custom_headers object

    A set of custom HTTP headers that will be included in requests to this webhook, provided as key-value pairs.

  • type
  • items string
  • timeout string

    The timeout that will be applied when calling this webhook.