Webhooks

When building Daimo Pay integrations, you may want your application to receive events related to your payment links as soon as they occur on-chain, so that your systems can track and execute actions accordingly.

With webhooks, our server can send you notifications when payment status updates occur in real-time. Start by setting up an endpoint on your server that can receive POST requests from us.

Setting up webhooks

A webhook can either be set up on the Pay Dashboard or programmatically via our API.

Manage webhooks on the Pay Dashboard

COMING SOON We recommend managing webhooks on the Pay Dashboard. Go to the "Webhooks" tab > "Create Webhook".

Create a webhook programmatically using the API

You can create a webhook by making a POST request to the /webhook endpoint.

Request parameters

curl --request POST 'https://pay.daimo.com/api/webhook' \
--header 'Idempotency-Key: <A unique idempotency key>' \
--header 'Api-Key: <Your API key>' \
--data-raw '{
  "url": "<Your webhook listener URL>"
}'

Response body

{
  "id": "<Webhook ID>",
  "url": "<Your webhook listener URL>",
  "token": "<Secret token to verify requests>"
}

Get a webhook using the API

You can get a webhook by making a GET request to the /webhook/:id endpoint.

Request parameters

curl --request GET 'https://pay.daimo.com/api/webhook/<Your webhook ID>' \
--header 'Api-Key: <Your API key>'

Response body

{
  "id": "<Webhook ID>",
  "url": "<Your webhook listener URL>",
  "token": "<Secret token to verify requests>"
}

Delete a webhook using the API

You can delete a webhook by making a DELETE request to the /webhook/:id endpoint.

Request parameters

curl --request DELETE 'https://pay.daimo.com/api/webhook/<Your webhook ID>' \
--header 'Idempotency-Key: <A unique idempotency key>' \
--header 'Api-Key: <Your API key>'

Response body

{
  "status": "success"
}

Consuming webhook events

Once you have created a webhook, we will deliver events to the specified URL via POST request any time a payment link you created receives a status update. The endpoint should return a 200 response as soon as possible to indicate that the event was successfully received.

Events

Currently, webhooks send the following events:

Payment started

Triggered when a user makes a valid payment on a payment link you created. This is when Daimo Pay triggers any necessary bridging and swapping actions on-chain to fulfill the payment to the recipient specified in the payment link.

{
  "type": "payment_started",
  "paymentId": "72hebvwpDJDA9qNubzb2jYjAbdDgjH4uD53rBnh8BR3A",
  "chainId": 137,
  "txHash": "0xec14e8d06ba0c40bc3fdd60916b3d9e75650ad685e30b73ea08ee6a003f44970"
}

Payment completed

Triggered when a payment link recipient has successfully received the payment and the related on-chain call (if any) has been executed successfully. Usually delivered a few seconds after the payment_started event, when the on-chain recipient transaction has been confirmed.

{
  "type": "payment_completed",
  "paymentId": "72hebvwpDJDA9qNubzb2jYjAbdDgjH4uD53rBnh8BR3A",
  "chainId": 8453,
  "txHash": "0xe8f859f1f618e782498abeec5bb963bfe248628c45e809971f256b2947d8ff7e"
}

Payment bounced

Triggered when a payment link recipient has a call that reverts on-chain, and instead a refund is triggered as described in refunds.

This is a rare event, but one that is important to track as it can adversely affect your application's user experience.

{
  "type": "payment_bounced",
  "paymentId": "72hebvwpDJDA9qNubzb2jYjAbdDgjH4uD53rBnh8BR3A",
  "chainId": 8453,
  "txHash": "0x..."
}

Verifying webhook requests

We use token based authentication to allow you to verify that webhook requests originate from us. When creating a webhook, we respond with a secret token. You should verify that any webhook event requests include a header Authorization: Basic <token> with this secret token.

Event delivery behavior

In normal operation, we will send events to your webhook as soon as they occur, and expect a 200 response from your endpoint.

In the event we don't receive a 200 response, we will retry delivery with an exponential backoff for up to a day before marking the event as failed. For best results, we recommend avoiding any assumptions about the event delivery behavior. In particular, we expect your endpoint to handle the following:

• Duplicate events: Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicates by using the Idempotency-Key header in our requests, and skipping keys you have already processed.

• Quickly return a 2xx response: Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout.

• Event ordering: We don't guarantee delivery of events in the order in which they're generated. For example, payment_completed may be sent before payment_started.

• Transactions may get re-orged out: While most chains Daimo Pay supports do not have re-orgs, it's possible that events on some chains inform you of transactions that got re-orged on-chain. We do not currently notify on re-orgs, but we plan to add support for that edge case in future.