{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/api-docs/best-practices/notification-webhooks/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Notification webhooks

\n

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.

\n

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

\n

Why use notification webhooks

\n

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.

\n
Note:

Ripple Payments Direct 2.0 doesn’t support authenticated callback URLs.

\n

Event types

\n

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.

\n\n

The following tabs show sample payloads for the payment state transition event with different payment states:

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

Event data of the PAYMENT_STATE_TRANSITION event do not include details such as error codes in case of a FAILED payment. This event type purely informs about payment state transitions.

\n\n

Configuration and security

\n

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

\n

1. Register callback URL

\n

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. We recommend a public URL that's accessible over the internet, but 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.

\n

2. Optional: Add Ripple IP addresses to your allowlist

\n\n

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

\n

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

\n

3. Optional: Verify webhook signatures

\n

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.

\n

To verify the webhook signatures:

\n
    \n
  1. \nRetrieve the webhook payload and the signature (from the header).\n

    Example

    \n
    \n
    \n
    Copy
    \n
    Copied!
    \n
    \n 
    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\"}\n\nHeaders:\nripple-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=\nripple-signature-timestamp: 2025-05-30T10:21:21.808586489Z
    \n
    \n
    2. \n
  2. \nCreate the hash of the request by concatenating the \nripple-signature-timestamp\n value and the request \nbody\n as a string separated by a period delimiter, for example:\n
    \n
    \n
    Copy
    \n
    Copied!
    \n
    \n 
    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\"}
    \n
    \n
    3. \n
  3. \nDecrypt the signature value using Ripple's public key that you obtained from your Ripple liaison.\n
    4. \n
  4. \nCompare the hash values, that is, the decrypted signature and the hashed value you created.\n

    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.

    \n
    5. \n
\n
Tip

Additionally, you can calculate the difference between the current timestamp and the received timestamp to decide whether the difference is acceptable.

\n

Response times and retry behavior

\n

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.

\n

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.

\n
Clarification

Delivery order is not guaranteed. Notifications may arrive out of sequence, especially if retries occur after downtime. Clients must design webhook handlers to handle out-of-order messages safely.

\n
Alternative to webhooks

As an alternative to using webhooks to receive notifications from Ripple Payments about changes to the status of your Ripple payments, you can use the POST /v2/payments/filter operation to poll payments by paymentStates and other properties. For more information about this operation, see POST Search payments.

","headings":[{"value":"Notification webhooks","depth":1},{"value":"Why use notification webhooks","depth":2},{"value":"Event types","depth":2},{"value":"Configuration and security","depth":2},{"value":"1. Register callback URL","depth":3},{"value":"2. Optional: Add Ripple IP addresses to your allowlist","depth":3},{"value":"3. Optional: Verify webhook signatures","depth":3},{"value":"Response times and retry behavior","depth":3}]},"contentItem":{"data":{"lastModified":"2025-11-13T00:24:58.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":false,"disableLastModified":true,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"12498b05-1619-544a-8f3d-7f4cd6141114__redocly content/api-docs/best-practices/notification-webhooks/","seo":{"title":"Notification webhooks","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"api-docs/best-practices/notification-webhooks.md","pageBaseUrl":"/api-docs/best-practices/notification-webhooks","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Notification webhooks","id":"notification-webhooks"},{"depth":2,"value":"Why use notification webhooks","id":"why-use-notification-webhooks"},{"depth":2,"value":"Event types","id":"event-types"},{"depth":2,"value":"Configuration and security","id":"configuration-and-security"},{"depth":3,"value":"1. Register callback URL","id":"1-register-callback-url"},{"depth":3,"value":"2. Optional: Add Ripple IP addresses to your allowlist","id":"2-optional-add-ripple-ip-addresses-to-your-allowlist"},{"depth":3,"value":"3. Optional: Verify webhook signatures","id":"3-optional-verify-webhook-signatures"},{"depth":3,"value":"Response times and retry behavior","id":"response-times-and-retry-behavior"}]},"data":{"title":""},"catalogInfo":null,"link":"/api-docs/best-practices/notification-webhooks/","sidebarName":"__root-sidebar__-data-69308394-sidebars.yaml","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}