Skip to main content

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 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, all related to reversal failure detection:

Checkout.com eventDescription
payment_refund_declinedA refund has been declined
payment_void_declinedA void has been declined
payment_refundedA refund notification (tracked if the operation failed)
payment_voidedA void notification (tracked if the operation failed)

Prerequisites​

Before setting up webhooks, ensure you have completed the general Checkout.com integration 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.
  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_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.