Webhooks

This guide covers how to create, edit, and manage Zendesk webhooks at GitLab. Administrators should review the Administrator tasks section.

Understanding webhooks

What are webhooks

As per Zendesk:

A webhook sends an HTTP request to a specified URL in response to an event, such as a trigger or automation firing in Zendesk Support. Web developers typically use webhooks to invoke behavior in another system.

Simplified, it is an HTTP request made to another system. These can be used for things such as GitLab issue creation, alerting Slack, etc.

Using a webhook in Zendesk

Webhooks are used exclusively by other items in Zendesk (usually Zendesk events, automations, and triggers). As such, you do not “directly” use them. You instead “indirectly” use them when the triggering object runs.

How we manage webhooks

We currently manage all webhooks within Zendesk itself.

Creating webhooks as a non-admin

For the creation of a webhook, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Editing webhooks as a non-admin

For the modification of a webhook, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Deleting webhooks as a non-admin

For the deletion of a webhook, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Administrator tasks

Viewing webhooks in Zendesk

1. Navigate to the admin dashboard for the Zendesk instance
   • Zendesk Global (production)
   • Zendesk Global (sandbox)
   • Zendesk US Government (production)
   • Zendesk US Government (sandbox)
2. Go to Apps and integrations > Webhooks > Webhooks
   • Zendesk Global
   • Zendesk Global (sandbox)
   • Zendesk US Government
   • Zendesk US Government (sandbox)

You can click on the webhook’s name for more information.

Viewing logs for a webhook

To view the logs for a webhook:

1. Go to the webhooks page
2. Click on the name of the webhook you wish to view the logs for
3. Click on the Activity tab

From there, you can click the Invocation ID of an event to see more details.

Testing a webhook

To test a webhook:

1. Go to the webhooks page
2. Click on the name of the webhook you wish to view the logs for
3. Click the Actions link at the top-right of the page
4. Click Test Webhook
5. Enter the payload information (what exactly you use will vary based off the webhook itself)
6. Click the Send test button

Webhook subscriptions

Webhooks use subscriptions to determine when they run. For more information on webhook subscriptions, see Zendesk’s documentation.

Webhook request formats

The valid request formats for Zendesk webhooks are:

• JSON (API value: json)
• XML (API value: xml)
• Form encoded (API value: form_encoded)

Webhook authentication

Webhooks can use the following authentication methods:

• None (API value: none)
• API Key (API value: api_key)
• Basic authentication (API value: basic_auth)
• Bearer token (API value: bearer_token)

The intricacies of how those work can be read about via Zendesk’s documentation

Creating a webhook

If the webhook is clean of sensitive information in its endpoint or custom headers, you can utilize the sync repo. However, if it contains sensitive information, such as an API token or a secret, in its endpoint/custom headers, you will need to create it in Zendesk itself. The preference should always be a setup that enables the use of the sync repo whenever possible.

When creating it using the sync repo, the exact changes being made will depend on the request itself. A starting template you can use would be:

---
name: 'Name of webhook'
previous_name: 'Name of webhook'
description: 'Description of webhook'
status: 'active'
subscriptions:
- 'subscription_to_use'
endpoint: 'URL to use'
http_method: 'Method type to use'
request_format: 'Format of the request'
authentication: null
custom_headers: null

After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.

If you need to create it manually in Zendesk:

1. Go to the webhooks page
2. Click the Create webhook button at the top-right of the page
3. Select the type of webhook
   • Events: Based off Zendesk events, such as user creation, organization modification, etc.
   • Trigger or automation: Run via trigger or automation
4. Click Next (at the bottom-right of the page)
5. If making an Events type webhook:
   1. Select the event types to use
   2. Click Next (at the bottom-right of the page)
6. Enter the name of the webhook
7. Enter a description for the webhook (optional)
8. Enter an endpoint URL (i.e. where a payload is sent)
9. Select the request method
10. Select the request format
11. Enter the type of authentication to use
12. Enter any additional headers needed (up to 5)
13. While optional, you will have the opportunity to test the webhook you are creating. You should do this to ensure it is going to work properly.
    • Clicking the button will bring up the test prompt. See Testing a webhook for more information.
14. Click Create webhook button at the bottom-right of the page

Editing a webhook

To edit a webhook, you will need to determine if it is managed in the sync repo or in Zendesk directly.

If it is managed via the sync repo, you will need to create a MR in the sync repo. The exact changes being made will depend on the request itself. After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.

If it is managed in Zendesk directly:

1. Go to the webhooks page
2. Click on the name of the webhook you wish to edit
3. Click the Actions link at the top-right of the page
4. Click Edit
5. Make the changes you need to make
6. While optional, you will have the opportunity to test the webhook you are modifying. You should do this to ensure it is going to work properly.
   • Clicking the button will bring up the test prompt. See Testing a webhook for more information.
7. Click the Update button at the bottom-right of the page

Changing the name of a webhook via the sync repo

If you need to change the name of a webhook, copy the current value into the previous_name attribute and then change the name attribute. This allows the sync to still locate the webhook in question to update.

Updating authentication information for a webhook via the sync repo

If you need to update the authentication information for a webhook, such as updating the API key used, there are some special steps you need to take in the sync repo itself:

1. Navigate to the sync repo
2. Navigate to the CI/CD settings
   • Zendesk Global
   • Zendesk US Government
3. Add a file type CI/CD variable named TOKENS

The contents of the CI/CD variable will be a JSON block with the information needed (encased in an Array).

As an example, if you needed to update the PRIVATE-TOKEN value for the webhook Do a thing to abc123, the contents of the TOKENS CI/CD file variable would be:

[
  {
    "name": "Do a thing",
    "PRIVATE-TOKEN": "abc123"
  }
]

That is then used by the sync repo to update the PRIVATE-TOKEN value for the webhook Do a thing on the next deployment run.

This method can be used to update the authentication information for multiple webhooks in one update:

[
  {
    "name": "Do a thing",
    "PRIVATE-TOKEN": "abc123"
  },
  {
    "name": "Do another thing",
    "PRIVATE-TOKEN": "def456"
  }
]

The deployment run ends by removing the CI/CD file variable TOKENS (to prevent it using that information to force another unneeded update on the next deployment run).

Deactivating a webhook

To deactivate a webhook, you will need to determine if it is managed in the sync repo or in Zendesk directly.

If it is managed via the sync repo, you will need to create a MR in the sync repo. In this MR, you should do the following to the corresponding trigger’s YAML file:

1. Move the file from the active to inactive path
2. Modify the value of the active attribute to false

After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.

If it is managed in Zendesk directly:

1. Go to the webhooks page
2. Click on the name of the webhook you wish to deactivate
3. Click the Actions link at the top-right of the page
4. Click Deactivate
5. Click Deactivate webhook to confirm the deactivation

Deleting a webhook

As the sync repos do not perform deletions, you will need to do this via Zendesk itself.

To delete a webhook in Zendesk:

1. Go to the webhooks page
2. Click on the name of the webhook you wish to delete
3. Click the Actions link at the top-right of the page
4. Click Delete
5. Click Delete webhook to confirm the deletion

Performing an exception deployment

To perform an exception deployment for webhooks managed by the sync repo, navigate to the webhooks sync project in question, go to the scheduled pipelines page, and click the play button for the sync item. This will trigger a sync job for the webhooks.

Monitoring

How it works

Using GitLab scheduled pipelines, the bin/process script runs every hour on the 15 minute mark (using UTC timezone). This script does the following:

• Gathers a list of all webhooks in the Zendesk instance
• Gathers a list of all invocations for each webhook (that ran in the last hour)
• Filters out the list of invocations to remove all successful invocations
• Posts in Slack for each non-successful invocation

Actioning on failed invocations

When you are alerted about failed invocations for a Zendesk instance, you should review the invocation itself to determine next steps. The exact action to perform will depend on the failure itself:

• If the failure stems from the payload used by Zendesk, file a bug issue
• If the failure stems from the endpoint:
  • Retry the invocation by:
    • Copying the Request body used
    • Testing the webhook tied to the invocation using a custom payload
  • If the retry fails, file a bug issue

Making changes to the webhook monitor

To modify the webhook monitor, you will need to create a MR in the corresponding project repo. The exact changes being made will depend on the request itself.

After a peer reviews and approves your MR, you can merge the MR. Being this is an Ad-hoc deployment type, the changes will be used in the next scheduled run.

Common issues and troubleshooting

This is a living section that will have items added to it as needed.

Not seeing webhook changes after a merge

As webhooks follow the Standard deployment type, they would only be deployed during a normal deployment cycle (or when an exception deployment has been done)

View page source - Edit this page - please contribute.