Outgoing Webhooks Integration Guide

Zenduty supports webhooks to easily integrate external applications.

Outgoing webhooks in Zenduty is a method of sending incident notifications to an application through an HTTP POST request when the following activities happen:
- Incident Triggered
- Incident acknowledged
- Incident Resolved

[Important] Your outgoing webhook receiver must respond to the request within 3 seconds.

Create an Outgoing webhook

1. Navigate to your service and within the integrations tab, click on Add integration under Outgoing Integrations.

2. From the applications list, select Outgoing Webhooks. Click on Save.

3. Click on config next to your new integration and navigate to the integration configuration page.

4. In the input box, add the URL to which you'd like to send the Webhook HTTP POST request.

5. You can create an outgoing webhook integration with no authentication or authenticate it using the Basic or HMAC Signature.

Basic Authentication

1. Click on the Edit button to create a username and password.

2. After entering your credentials, click on Save to store them.

3. Once these steps are completed, our system is configured to automatically append the Basic Auth header to any requests dispatched to the specified webhook URL.

When you receive a webhook from our system with basic authentication, it will include the Basic Auth header in the headers. This header is used to verify the authenticity of the request.

Note: The Basic Authentication transmits credentials in an ‘Authorization’ header, encoded in Base64.

Signature Authentication

For signature verification, choose the desired signature method from the dropdown menu and save the displayed signing key. The key will be automatically copied to your clipboard for convenience. With this setup, our system will verify the signature of incoming requests using the specified method and key, ensuring secure communication between parties.

Once you enable the Signature verification for the webhook, Download and save your signing key, this key is going to be used to verify the the authenticity of the webhook and that it is not tempered with.

When you receive a webhook from our service, it includes an HMAC signature that you can use to verify the request originated from us. The signature is computed using the SHA256 algorithm with a secret key that you possess.

Click on Save and then Test webhook to test your webhook integration.

The payload sent by Zenduty will look like the payload below:


```
{
    "payload": {
        "event_type": "triggered",
        "incident": {
            "summary": "test summary example",
            "incident_number": 60,
            "creation_date": "2019-06-07T22:47:28.431949Z",
            "status": 1,
            "unique_id": "pprkCF8ghaUcFMFT",
            "title": "Webhook Test Title",
            "incident_key": "8Di7LnwobtX4qCb7n",
            "service": {
                "name": "Payments",
                "creation_date": "2019-03-14T08:36:51.064063Z",
                "summary": "Test summary",
                "description": "Test description",
                "unique_id": "9ea1cd16-22fe-45c9-a22d-b74f95305b6d",
                "auto_resolve_timeout": 0,
                "created_by": "a80cde9a-3e6a-48de-8a98-1",
                "acknowledgement_timeout": 0,
                "status": 1,
                "escalation_policy": "5fac37b562834cdaadda2429b1a04f22",
                "team": "910825254a64446fae1fb94744ab343b",
            },
            "priority": 1,
            "urgency": 1,
            "merged_with": None,
            "assigned_to": {
                "username": "a80cde9a-3e6a-48de-8a98-1",
                "first_name": "TestFirstName",
                "last_name": "TestLastName",
                "email": "test@test.com",
            },
            "resolved_date": None,
            "acknowledged_date": None,
            "context_window_start": None,
            "context_window_end": None,
        },
    }
```

There are three 'event_type' values sent by Zenduty - 'triggered',
'acknowledged' and 'resolved'.

Steps to verify the HMAC signature:

1. Extract the HMAC Signature: Extract the HMAC signature from the incoming request. The signature is usually found in the headers of the request. The header key is named X-SIGNATURE

2. The signing key: The signing key is the Secrate key which is generated earlier.

3. Compute the HMAC Signature: Compute the HMAC signature on your end using the same method we used to generate the signature.

Below is an implementation of how you can verify the signature - this example uses Python but the steps remain the same regardless of the language you use.

    
import hmac
import hashlib
import base64
import json


def compute_signature(data, key):
   key = bytes(key, "utf-8")
   message = bytes(json.dumps(data), "utf-8")
   signature = hmac.new(key, message, hashlib.sha256).digest()
   computed_hmac = base64.b64encode(signature)
   return computed_hmac
   

In this function, data is the payload of the incoming request and key is your signing key(integration key of the integration).

4. Compare Signatures: Compare the HMAC signature you computed with the HMAC signature you received in the request. If they match, the request is verified.

IMPORTANT:

• The data used to compute the HMAC signature should be exactly the same as the data sent in the request. Any changes to the data, including adding or removing whitespace, will result in a different signature.

• Keep your secret key secure. Do not expose it.

Custom Headers

There is also an option to add custom headers which will be sent along with the headers sent by default.

To add custom headers, click on the add headers option, fill in your desired key-value pairs and click on add.

Note: Spaces are not allowed in headers