# Integration Webhook

An integration webhook delivers immediate notifications to your internal systems when an integration enters a Warning or Error state. This enables timely detection and response to issues, helping prevent downstream impact.

***

### Prerequisites

<table><thead><tr><th width="190.02734375">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>Target System API</strong></td><td><p>Authentication information used when making requests to the target system</p><p>Apono supports the following authentication:</p><ul><li>Bearer Token</li><li>OAuth</li><li>Custom (key-value pairs passed in the header)</li></ul><p><br>This is required only if the system receiving the webhook notifications requires authentication.</p></td></tr><tr><td><strong>Target System Webhook URL</strong></td><td>URL of the target system that will receive the webhook</td></tr></tbody></table>

***

### Configure a webhook

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfopw2yNxONoIjVNxHrSA0YFqVh1c2KfFDdsat_dMH5PZSQKwyOLocYdwsvG2vuCDz_Tug-hCWa-bDq21kC9w2ayTC5ZDIVrQJjqjkcWePYlA6NqBy7y5DORlVintGIQ_9ts_KoSw?key=ljUoAVpu6_U6T_xEExAgWeZ_" alt="" width="563"><figcaption><p>Integration webhook setup</p></figcaption></figure>

Follow these steps to configure an Apono webhook:

1. On the [**Webhooks**](https://app.apono.io/webhooks) page, click **Add Webhook**. The **Add Webhook** page appears.
2. Click **Integration**.
3. Enter a unique, alphanumeric, user-friendly **Integration Webhook Name** for identifying this webhook.
4. Click the **Status** toggle to **Active**.
5. From the **Type** dropdown menu, select **HTTP Webhook**.
6. From the **Method** dropdown menu, select the **POST** method.
7. For the **URL** field, enter the URL of the target system that will receive the webhook.

{% hint style="warning" %}
The webhook URL must use the HTTPS protocol.
{% endhint %}

8. In the **Body Template** field, construct a JSON body for the webhook payload. The following is an example webhook payload.

```json
{
  "event_type": "{{event_type}}",
  "event_time": "{{event_time}}",
  "data": {
    "id": "{{data.id}}",
    "name": "{{data.name}}",
    "type": "{{data.type}}",
    "status": "{{data.status}}",
    "issues": [
      {
        "status": "{{data.issues.status}}",
        "message": "{{data.issues.message}}"
      }
    ]
  }
}
```

{% hint style="success" %}
Click **View event's payload schema** to reveal the payload schema and available data fields.
{% endhint %}

9. (Optional) If applicable, enter the authentication information required by the target system.

{% tabs %}
{% tab title="Bearer Token" %}
Follow this step to add Bearer Token authentication:

1. Under **Headers**, use the **Key** and **Value** fields to set the access token.

| Key             | Value                  |
| --------------- | ---------------------- |
| *Authorization* | *Bearer \<API\_TOKEN>* |
| {% endtab %}    |                        |

{% tab title="OAuth" %}
Follow these steps to add OAuth authentication:

1. From the **Authentication Type** dropdown menu, select **OAuth**. The OAuth settings appear.
2. Define the OAuth settings.

<table><thead><tr><th width="204">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>Client ID</strong></td><td>Unique identifier assigned by the authorization server</td></tr><tr><td><strong>Client Secret</strong></td><td>Secret key issued by the authorization server</td></tr><tr><td><strong>Token Endpoint URL</strong></td><td>URL where the authorization code or refresh token is exchanged for an access token</td></tr><tr><td><strong>Scopes</strong></td><td>(Optional) Set of permissions requested to access specific resources or APIs</td></tr></tbody></table>
{% endtab %}

{% tab title="Custom" %}
Follow these steps to add custom authentication:

1. Under **Headers**, use the **Key** and **Value** fields to set the credential information.
2. If your tool or service has several values, enter each key-value pair in a separate row.

{% hint style="info" %}
The following example uses [Datadog](https://docs.apono.io/docs/webhook-integrations/request-webhook/logs-and-siems/datadog) as an example.
{% endhint %}

| Key                  | Value        |
| -------------------- | ------------ |
| *DD-API-KEY*         | *\<API KEY>* |
| *DD-APPLICATION-KEY* | *\<KEY ID>*  |
| {% endtab %}         |              |
| {% endtabs %}        |              |

10. Under **Filters**, define one or several filters from the **Integration**, **Type**, and **Status** dropdown menus.

{% hint style="info" %}
Filters empower admins to control the data transmitted via webhooks, minimizing the amount of data third-party tools receive and reducing unnecessary clutter.

Use these filters to scope notifications to specific integrations, integration types, or status changes, such as **Error**, **Warning**, or **Active**.
{% endhint %}

11. (Optional) In the **Timeout in seconds** field, enter the duration in seconds to wait before marking the request as failed.
12. (Optional) Define **Response Validators** to verify that the response from the webhook meets specified criteria:
    1. Click **+ Add.** A row of settings appears.
    2. Starting with *$.data.*, enter the **Json Path** of the JSON parameter.
    3. In the **Expected Values** field, enter a value and press the Enter key on your keyboard.
    4. Repeat step **c** to add several expected values.
    5. Repeat steps **a-d** to add multiple response validators.
13. Click **Test** to generate a test event to trigger your webhook. A **Test successful** or **Test failed** response status will appear at the bottom of the page. A successful test will send mock data to the target system.

{% hint style="success" %}
For more information about the test, click **View Invocation Data**. A panel opens revealing the request, response, and other relevant details.

Should your test fail, view these tips to [troubleshoot your webhook](https://docs.apono.io/docs/webhook-integrations/troubleshoot-a-webhook).
{% endhint %}

14. Click **Save Webhook**.

The new webhook appears in the **Webhooks** table. Active webhooks are marked with a green dot. Inactive webhooks are marked with a white dot.

Apono notifications will be sent to your target system when the status of an integration has changed to a warning or error state.