Skip to main content

Setting up Webhooks

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

Overview​

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

note

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

PayPal eventDescription
PAYMENT.CAPTURE.REFUNDEDA capture has been refunded (tracked if the status indicates failure)
PAYMENT.CAPTURE.REVERSEDA capture has been reversed (tracked if the status indicates failure)
PAYMENT.AUTHORIZATION.VOIDEDAn authorization has been voided (tracked if the status indicates failure)

Prerequisites​

Before setting up webhooks, ensure you have completed the general PayPal 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 ID field — you will fill this in after subscribing the webhook in PayPal (Step 3).
important

Unlike other payment providers, PayPal requires a Webhook ID instead of a webhook secret. The Webhook ID is not a secret value — it is a PayPal-assigned identifier for your webhook subscription that Odus uses for certificate-based signature verification.

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 Webhook ID fields are available in the edit form.

Step 2 — Subscribe a webhook listener in PayPal​

  1. Log in to the PayPal Developer Dashboard.
  2. Navigate to Apps & Credentials.
  3. Select the REST API app that you are using for your Odus integration.
  4. Scroll down to the Webhooks section.
  5. Click Add Webhook (or "Subscribe a listener URL").
  6. Paste the Webhook URL you copied from the Odus Dashboard into the Listener URL field.
  7. Select the following event types:
    • PAYMENT.CAPTURE.REFUNDED
    • PAYMENT.CAPTURE.REVERSED
    • PAYMENT.AUTHORIZATION.VOIDED
  8. Click Save.
important

PayPal requires the webhook listener URL to use HTTPS on port 443. Ensure that your Odus API is accessible over HTTPS.

Step 3 — Copy the Webhook ID to Odus​

After subscribing the webhook listener:

  1. In the Webhooks section of your PayPal app, locate the webhook you just created. PayPal assigns a Webhook ID to each listener upon creation.
  2. Copy the Webhook ID.
  3. Go back to the Odus Dashboard — either in the Webhook Setup dialog (if still open) or by editing the gateway profile.
  4. Paste the Webhook ID into the Webhook Verification Key field (labeled "Webhook ID" for PayPal integrations).
  5. Click Save.

Important notes​

  • PayPal retries webhook deliveries for up to 3 days, making up to 25 retry attempts on non-2xx responses.
  • After 3 days of failed delivery, the event is marked as failed but can be resent manually from the PayPal Webhook Events Dashboard.
  • You can subscribe up to 10 webhook URLs per PayPal REST API app.
  • Only events from the specific REST API app are delivered. If you have multiple apps, each requires its own webhook subscription.
  • PayPal uses certificate-based signature verification (not HMAC). The Webhook ID you provide to Odus is used as part of this verification process.