# Setting up Webhooks

Learn how to configure ODUS to receive webhook notifications from Checkout.com.

## Overview

Webhooks allow Checkout.com to notify ODUS about events that happen asynchronously, such as declined captures, refunds or voids. When properly configured, ODUS will automatically process these notifications and update the corresponding payment records.

note

ODUS currently processes the following Checkout.com webhook events:

| Checkout.com event         | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `payment_capture_declined` | A capture has been declined                             |
| `payment_refund_declined`  | A refund has been declined                              |
| `payment_void_declined`    | A void has been declined                                |
| `payment_refunded`         | A refund notification (tracked if the operation failed) |
| `payment_voided`           | A void notification (tracked if the operation failed)   |

## Declined captures

Checkout.com accepts a capture request first and approves or declines it afterwards. ODUS records the capture as soon as Checkout.com accepts it, so a capture that Checkout.com declines later is only corrected when the `payment_capture_declined` event arrives.

When it arrives, ODUS:

* marks the transaction's capture as failed, and sends you [`transaction.capture_failed`](https://docs.odus.com/docs/api/core/v2/webhook-transaction-capture-failed);
* leaves the payment authorized and uncaptured, so you can capture it again or cancel it;
* stops capturing that payment automatically, including a payment with a delayed automatic capture.

warning

If your webhook configuration does not include `payment_capture_declined`, a declined capture stays captured in ODUS and no error is reported. Funds for that payment never arrive.

## Declined refunds and voids

Checkout.com can also decline a refund or a void after accepting it. ODUS records the refund or void as soon as Checkout.com accepts it, so one that Checkout.com declines later is only corrected when the `payment_refund_declined` or `payment_void_declined` event arrives.

When it arrives, ODUS:

* takes the declined refund or void off the payment's reversed amount, so the payment shows what Checkout.com actually did. A declined partial refund leaves any other refunds of the payment in place;
* marks the transaction's refund or void as failed, and sends you [`transaction.reverse_failed`](https://docs.odus.com/docs/api/core/v2/webhook-transaction-reverse-failed). You receive it once per transaction: if a second refund of the same transaction is declined, ODUS corrects the reversed amount without sending it again;
* lets you refund or void the payment again.

warning

If your webhook configuration does not include `payment_refund_declined` and `payment_void_declined`, a declined refund or void stays recorded in ODUS and no error is reported. The shopper is not refunded, or the hold on their card is not released.

## Prerequisites

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

Your Checkout.com user needs the **Admin** or **Developer** role, or a custom role with the following permissions:

* Create, edit and delete workflow notifications
* View secret keys
* View the list of workflow notifications

## 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 Checkout.com (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 configuration in Checkout.com

1. Log in to the [Checkout.com Dashboard](https://dashboard.checkout.com/).

2. Click the **Developers** icon in the top navigation bar.

3. Open the **Webhooks** tab.

4. Click **Create configuration**.

5. Enter a **Name** for the webhook (e.g., "ODUS").

6. Paste the **Webhook URL** you copied from the ODUS Dashboard into the **Endpoint URL** field.

7. Next to the **Signature key** field, click **Generate key** to create a new signature key and copy it immediately.

8. Select the following **event types**:

   <!-- -->

   * `payment_capture_declined`
   * `payment_refund_declined`
   * `payment_void_declined`
   * `payment_refunded`
   * `payment_voided`

9. Select the appropriate **entities or processing channels** to receive webhooks for.

10. Click **Create webhook**.

## Step 3 — Copy the signature key to ODUS

1. After generating the signature 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 signature key into the **Webhook Verification Key** field.
4. Click **Save**.

## Important notes

* Checkout.com responds to webhook delivery failures with automatic retries — up to **8 times** at increasing intervals (5 min, 10 min, 15 min, 30 min, 1 hour, 4 hours, 12 hours, 12 hours).
* Webhook endpoints must respond within **10 seconds**, otherwise the delivery is considered failed and will be retried.
* Webhook delivery order is **not guaranteed**.
* You can suspend, restore, or delete webhook configurations from the Checkout.com Dashboard at any time.