Webhook endpoints
Webhook endpoints are alert or incident webhooks designed to be triggered from within a workflow. When used in conjunction with a workflow, a webhook endpoint can be used to create and update payloads on externally connected (outbound) systems, such as ITSM/ticketing, notification, or collaboration tools.
Alert webhook endpoints are used in alert workflows, and incident webhook endpoints are used in incident workflows. While webhook endpoints are triggered from a workflow, they include a second set of optional triggers to allow flexibility in your workflow design. For example, a workflow could trigger for all alert updates, but an alert webhook endpoint in the workflow could have the triggers configured to only send a payload when the assignee changed. This separation of triggering can allow the workflow to perform other work in addition to sending a payload via the webhook endpoint.
Determine how many webhook endpoints you need
Begin by planning your approach, whether you are creating an alert or an incident webhook endpoint.
In most cases, you must create separate webhook endpoints for each CREATE and UPDATE payload. Because a distinct payload is associated with each webhook endpoint, you must create a separate webhook endpoint for each activity which requires a different payload. This can result in the creation of several webhook endpoints, so it is important to give them descriptive names for reference in the future.
If the remote service supports a single endpoint which can receive a webhook to trigger either a CREATE or UPDATE action, then you can use a single webhook endpoint, as long as you choose an appropriate HTTP request method (POST, PATCH, etc. ). In this scenario, everything the remote endpoint requires to process the CREATE/UPDATE message must be included in the body of the webhook endpoint, or URL-encoded into the URL. Note, however, that such a webhook endpoint cannot generate one message for CREATE operations and a different message for UPDATE operations.
If the remote service requires one endpoint (URL and body combination) for processing CREATE messages, and a separate endpoint (URL and body combination) for handling UPDATE messages, then you must create multiple webhook endpoints to perform the different activities.
The actual number of webhook endpoints you need to create varies, depending on the external system setup and on your goals.
Add a new webhook endpoint
To create a new webhook endpoint, navigate to Integrations > Outbound Integrations. Click Webhook Endpoint in the list, then select either the Alert Webhook Endpoint tab (to add an endpoint to use with alert workflows) or the Incident Webhook Endpoint tab (to add an endpoint to use with incident workflows). Click the button to add a new webhook endpoint, and complete the configuration.
Configure the webhook endpoint as follows. The instructions for both alert and incident webhook endpoints are essentially the same.
For a CREATE payload
Name and Description
The name for the webhook endpoint must be unique within the instance. It is recommended that you include the words “create” or “update” in your naming convention (example: "ServiceNow_create").
Caution
Do not use special characters when defining the name for a webhook endpoint, as they are not supported. Examples of special characters include (but not limited to):
-,\,/, or blank spaces.Configure webhook endpoint triggers
Triggers are optional. You can choose to trigger the webhook endpoint using the properties of the workflow trigger, or you can configure an additional trigger in the webhook endpoint to send data for a subset of the alerts or incidents.
For an UPDATE payload
Name and Description
The name for the webhook endpoint must be unique within the instance. It is recommended that you include the words “create” or “update” in your naming convention (example: "ServiceNow_update").
Caution
Do not use special characters when defining the name for a webhook endpoint, as they are not supported. Examples of special characters include (but not limited to):
-,\,/, or blank spaces.Configure webhook endpoint triggers
As with the triggers for CREATE payloads, triggers in the webhook endpoint configuration are optional for webhook endpoints sending UPDATE payloads.
Create the workflow
After you have created and validated the webhook endpoint, you must create a workflow of the applicable type with a Send to Endpoint action to trigger it. Create an alert workflow to trigger alert webhook endpoints, and an incident workflow to trigger incident webhook endpoints.