Skip to main content

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 codeDescription
REFUND_FAILEDA refund has explicitly failed
REFUNDA refund notification (tracked if success is false)
REFUND_WITH_DATAA refund with additional data (tracked if success is false)
CANCELLATIONA cancellation/void (tracked if success is false)
TECHNICAL_CANCELA technical cancellation (tracked if success is false)
CANCEL_OR_REFUNDA cancel-or-refund action (tracked if success is false)

Prerequisites​

Before setting up webhooks, ensure you have completed the general Adyen integration 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 (test) or 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 and HTTP POST.
    • 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.

  1. 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​

  • 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).