Notification webhooks

Webhooks are a recommended best practice to receive notifications from Ripple Payments Direct 2.0 about changes to the status of your payments instead of repeatedly polling for updates.

This topic provides an overview of how to use webhooks with Ripple Payments Direct.

Why use notification webhooks

A webhook is a method by which a service can notify a client application of relevant events, by sending notification messages to a callback URL that the client has registered with the service. When an event occurs, the service sends a notification to the specified callback URL — using the HTTP POST method — to let the client know that information is available about the event. This saves the client from having to continuously poll the service for new information.

Event types

Ripple Payments Direct 2.0 currently supports webhook notifications for the PAYMENT_STATE_TRANSITION event type. When a payment transitions from one state to another, the service sends a notification to the registered callback URL containing information about the event. For more information, see Register callback URL.

The following example shows a typical payload for a payment state transition event:

{
    "id":"4d3f90cf-b70f-5ff1-827a-f8aa9cf84ab9", // The ID of the webhook notification
    "eventType":"PAYMENT_STATE_TRANSITION", // The type of event
    "eventVersion":1, // The version of the event. The version number may change if the event data changes
    "eventData": { // The data of the event
        "paymentId":"5ce2c433-a96d-48d0-8857-02637a60abf4", // The ID of the payment to which the event corresponds
        "expiresAt":"2025-07-28T17:18:35.663Z", // The time when the payment expires
        "createdAt":"2025-05-29T17:18:35.663Z", // The time when the payment was created
        "sourceCurrency":"USD", // The source currency of the payment
        "sourceAmount":8, // The source amount corresponding to the source currency of the payment
        "destinationCurrency":"COP", // The destination currency of the payment
        "payoutAmount":32538.81, // The payout amount corresponding to the destination currency of the payment
        "paymentState":"VALIDATING", // The state that the payment is currently in
        "beneficiaryToken":"cb207125-73a7-4a94-8502-a7780f1cae78" // The ID of the payment beneficiary
    },
    "createDate":"2025-05-30T10:21:20.468Z" // The time when the webhook notification was created
}

Configuration and security

To start receiving webhook notifications, follow these steps to register a callback URL and add a Ripple IP address to your allowlist:

1. Register callback URL

At the time you onboard with Ripple Payments Direct 2.0, you need to provide a callback URL to which Ripple Payments Direct 2.0 can send notifications when events occur. This must be a public URL that's both accessible over the internet and restricted for access. The callback URL needs to be an HTTPS URL (not HTTP) with a public key certificate. Contact your Ripple liaison to register your webhook callback URL. This URL is configured in the Ripple Payments instance for your client application.

2. Add Ripple IP address to your allowlist

To ensure that webhook callbacks originate from Ripple Payments, you may need to add the Ripple Payments IP addresses to your server’s allowlist.

For a list of IP addresses to add to your allowlist, contact your Ripple liaison.

3. Optional: Verify webhook signatures

To make sure that all webhook notifications are generated by Ripple, you can verify the webhook signatures using a public key that you can obtain from your Ripple liaison.

To verify the webhook signatures:

1. Retrieve the webhook payload and the signature (from the header).

   Example

   Copy

   Copied!

   Body: {"id":"4d3f90cf-b70f-5ff1-827a-f8aa9cf84ab9","eventType":"PAYMENT_STATE_TRANSITION","eventVersion":1,"eventData":{"paymentId":"5ce2c433-a96d-48d0-8857-02637a60abf4","expiresAt":"2025-07-28T17:18:35.663Z","createdAt":"2025-05-29T17:18:35.663Z","sourceCurrency":"USD","sourceAmount":8,"destinationCurrency":"COP","payoutAmount":32538.81,"paymentState":"VALIDATING","beneficiaryToken":"cb207125-73a7-4a94-8502-a7780f1cae78"},"createDate":"2025-05-30T10:21:20.468Z"}
   
   Headers:
   ripple-signature: fcSWDhoHpNd+ZAQ2REndD7jacC1askGqltuXvFxp4MPWQ64w4cVz6yuvq3dAG/3pvCoJA10qXi/SCnvSXJajVKuOknU0WATEifQ+Zs4J06pCt2M0V8Ogcq2WIZ0+NUb2zvDfRr2o5UuzXVbEgDzZL0lC9s3PATQfcm3sJyYBSrCC35qf2NbkFye8i57jUPK8slEYwCwq6W+O+V1nFkNN6YMLi8MAHDSBsdGK+o/L1oCCckDaCFtMUaewVe15GKaQs6pHsVeLK0d7xgJmGciAnaifr7Ta2pv6dX4kTpIBzxy08VKiXHCRoRxZIyDF33jfHp5zVr/2H9xssGytZpDTkkSYYlgGNRS/mZxErE6Mddk2AN9ChMiWBq3TlMNLRCy3fCsICfLp/LqMqmU6/gr9uY41geLyzgozq2IanG4dHBuzHvyW8YykyeuifzFRKu4ykyKZpHTlYGe+ibDAh8Oo3XoO4iPe1NBqCFK+4EyjVgOa4LKT5XOBUxoXVUS4AxMun4MyPGNrOYVvLR2dzUc/5KeXVpWE4est6+XWLpSQduxRTwoeRHK7NdDyestKecWr0RS4le9FmvogBkuoCiMbMBrv+e0J9/A1X3txVXI+s6Zi72TwO6GqBAJx0bYRvAdKp3L9N2hcnd+P7NCnDKpb+hxc8+WeFkJcwtnqIupUVhw=
   ripple-signature-timestamp: 2025-05-30T10:21:21.808586489Z

2. Create the hash of the request by concatenating the ripple-signature-timestamp value and the request body as a string separated by a period delimiter, for example:
   Copy

   Copied!

   2025-05-30T10:21:21.808586489Z.{"id":"4d3f90cf-b70f-5ff1-827a-f8aa9cf84ab9","eventType":"PAYMENT_STATE_TRANSITION","eventVersion":1,"eventData":{"paymentId":"5ce2c433-a96d-48d0-8857-02637a60abf4","expiresAt":"2025-07-28T17:18:35.663Z","createdAt":"2025-05-29T17:18:35.663Z","sourceCurrency":"USD","sourceAmount":8,"destinationCurrency":"COP","payoutAmount":32538.81,"paymentState":"VALIDATING","beneficiaryToken":"cb207125-73a7-4a94-8502-a7780f1cae78"},"createDate":"2025-05-30T10:21:20.468Z"}

3. Decrypt the signature value using Ripple's public key that you obtained from your Ripple liaison.
4. Compare the hash values, that is, the decrypted signature and the hashed value you created.

   If the values match, the webhook is authentic and hasn't been tampered with. Otherwise, if they don't match, you should reject the webhook.

Response times and retry behavior

If a webhook notification delivery fails, that is, when the client responds with any status code other than 2xx, Ripple Payments Direct 2.0 will retry the notification up to 75 times (or 72 hours). The delay between retries is 30 seconds after the first failure and up to one hour after each subsequent failure.

Retries and other network issues may cause duplicate notifications to be sent. For that case, Ripple recommends that you maintain a list for the duplicate notifications.