# Setting up Webhooks

Learn how to configure ODUS to receive webhook notifications from Adyen.

## Overview

Webhooks allow Adyen to notify ODUS about events that happen asynchronously, such as failed refunds or cancellations. When properly configured, ODUS will automatically process these notifications and update the corresponding payment records.

note

ODUS currently processes the following Adyen webhook events, all related to reversal failure detection:

| Adyen event code   | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `REFUND_FAILED`    | A refund has explicitly failed                                  |
| `REFUND`           | A refund notification (tracked if `success` is `false`)         |
| `REFUND_WITH_DATA` | A refund with additional data (tracked if `success` is `false`) |
| `CANCELLATION`     | A cancellation/void (tracked if `success` is `false`)           |
| `TECHNICAL_CANCEL` | A technical cancellation (tracked if `success` is `false`)      |
| `CANCEL_OR_REFUND` | A cancel-or-refund action (tracked if `success` is `false`)     |

## Prerequisites

Before setting up webhooks, ensure you have completed the general [Adyen integration](https://docs.odus.com/docs/guides/integrations/gateways/adyen/.md) and have a working gateway profile in ODUS.

Your Adyen user needs the **Merchant admin** or **Merchant technical integrator** role to create and manage webhooks.

## Step 1 — Get the webhook URL from ODUS

When you create a new gateway profile in the ODUS Dashboard, a **Webhook Setup** dialog appears automatically after the profile is created. This dialog provides:

1. A **Webhook URL** — a read-only field with a copy button. This URL points to the ODUS webhook endpoint and includes your merchant and gateway profile identifiers as query parameters. Copy this URL; you will need it in the next step.
2. A **Webhook Verification Key** field — you will fill this in after configuring the webhook in Adyen (Step 3).

tip

If you skipped the webhook setup during gateway profile creation, you can still configure it later by editing the gateway profile in the ODUS Dashboard. The webhook URL and verification key fields are available in the edit form.

## Step 2 — Create a webhook in Adyen

1. Log in to the [Adyen Customer Area](https://ca-test.adyen.com/) (test) or [ca-live.adyen.com](https://ca-live.adyen.com/) (live).

2. Navigate to **Developers > Webhooks**.

3. Click **+ Create new webhook**.

4. Select **Standard** from the list and click **Add**.

5. Under **General**:

   <!-- -->

   * Toggle **Enabled** on.
   * Select the appropriate **Merchant accounts** (the merchant account used for your ODUS integration).

6. Under **Server configuration**:

   <!-- -->

   * Paste the **Webhook URL** you copied from the ODUS Dashboard into the **URL** field.
   * Set the **Method** to **JSON**. ODUS reads only JSON. It rejects every webhook sent in the **HTTP POST** or **SOAP** format, so none of them updates your payments.
   * Set the **Encryption protocol** to **TLSv1.2** or **TLSv1.3**.

7. Under **Events**, subscribe to the following event types:

   <!-- -->

   * `REFUND_FAILED`
   * `REFUND`
   * `REFUND_WITH_DATA`
   * `CANCELLATION`
   * `TECHNICAL_CANCEL`
   * `CANCEL_OR_REFUND`

8. Under **Security**, click **Generate** to create a new HMAC key.

warning

The HMAC key is shown **only once** after generation. Copy it immediately before proceeding.

9. Click **Save configuration**.

## Step 3 — Copy the HMAC key to ODUS

1. After generating the HMAC key in the previous step, copy it.
2. Go back to the ODUS Dashboard — either in the Webhook Setup dialog (if still open) or by editing the gateway profile.
3. Paste the HMAC key into the **Webhook Verification Key** field.
4. Click **Save**.

## Important notes

* If Adyen reports that webhooks to ODUS are failing, check that the webhook's **Method** is **JSON** and that the **Webhook Verification Key** in your ODUS gateway profile matches the HMAC key in Adyen.
* Adyen does **not** copy webhook configurations from test to live. You must create separate webhook configurations for each environment.
* Adyen expects a `2xx` response within **10 seconds**. If the response is delayed or missing, the event is queued for retry.
* In **live** environments, Adyen requires HTTPS on ports **443**, **8443**, or **8843**. In test environments, HTTP is also accepted on ports 80, 8080, or 8888.
* After generating a new HMAC key, Adyen continues to accept events signed with the old key for a short propagation period.
* If you need to allowlist Adyen's IP addresses for firewall rules, use the domain `out.adyen.com` (Adyen does not provide a static IP list).