Skip to main content

Setting up Webhooks

Learn how to configure Odus to receive webhook notifications from Stripe.

Overview​

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

note

Odus currently processes the following Stripe webhook events, all related to reversal failure detection:

Stripe eventDescription
refund.failedA refund has failed
refund.createdA refund has been created (tracked if failed)
refund.updatedA refund has been updated (tracked if failed)

Prerequisites​

Before setting up webhooks, ensure you have completed the general Stripe integration and have a working gateway profile in Odus.

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 Stripe (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 endpoint in Stripe​

  1. Log in to the Stripe Dashboard.
  2. Navigate to Workbench > Webhooks (or go directly to https://dashboard.stripe.com/webhooks).
  3. Click Create an event destination.
  4. For the event source, select Your account (Stripe account).
  5. Select the following event types to listen to:
    • refund.failed
    • refund.created
    • refund.updated
  6. Click Continue, then select Webhook endpoint as the destination type.
  7. Click Continue and paste the Webhook URL you copied from the Odus Dashboard into the Endpoint URL field.
  8. Save the configuration.
important

If you are using Stripe in live mode, the endpoint URL must use HTTPS. In test mode, HTTP is also accepted.

Step 3 — Copy the signing secret to Odus​

After creating the webhook endpoint in Stripe:

  1. In the Webhooks section of the Stripe Dashboard, select the endpoint you just created.
  2. Click Click to reveal to display the signing secret. It starts with whsec_.
  3. Copy the signing secret.
  4. Go back to the Odus Dashboard — either in the Webhook Setup dialog (if still open) or by editing the gateway profile.
  5. Paste the signing secret into the Webhook Verification Key field.
  6. Click Save.
warning

Stripe generates a unique signing secret per endpoint. If you are using both test and live mode, each will have its own signing secret — make sure you use the correct one for the corresponding Odus gateway profile.

Important notes​

  • Stripe retries webhook deliveries for up to 3 days with exponential backoff in live mode.
  • Webhook events are not guaranteed to arrive in chronological order.
  • You can roll your signing secret periodically in the Stripe Dashboard. When doing so, Stripe allows a grace period of up to 24 hours during which both the old and new secrets are accepted.