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.

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

Create and manage webhooks using the Webhooks API. Once you have created a webhook, we will deliver events to the specified URL via POST requests any time a Payment you created receives a status update. Your webhook endpoint should return a 200 response as soon as possible to indicate that the event was successfully received.

Webhook Events

Payment Started

Triggered when a user makes a valid payment on a Payment you created. After this event, Daimo Pay triggers any necessary bridging and swapping actions on-chain to fulfill the action specified in the Payment.

Name
type
Type
string
Description
Type of the event, in this case payment_started.
Name
paymentId
Type
string
Description
Unique id of the Payment.
Name
chainId
Type
number
Description
Chain ID of the network where the user made the payment.
Name
txHash
Type
string
Description
Transaction hash of the user's payment on chainId.
Name
payment
Type
object
Description
The Payment object corresponding to this event.

EVENT

payment_started

{
  "type": "payment_started",
  "paymentId": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "chainId": 10,
  "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
  "payment": {
    "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
    "status": "payment_started",
    "createdAt": "1739554073",
    "display": {
      "intent": "Pay Daimoo",
      "paymentValue": "1.00",
      "currency": "USD"
    },
    "source": {
      "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
      "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
      "chainId": "10",
      "amountUnits": "1.00",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
    },
    "destination": {
      "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
      "txHash": null,
      "chainId": "8453",
      "amountUnits": "1.00",
      "tokenSymbol": "DAI",
      "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "calldata": "0x"
    },
    "externalId": null,
    "metadata": null
  }
}

Payment Completed

Triggered when a Payment 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.

Name
type
Type
string
Description
Type of the event, in this case payment_completed.
Name
paymentId
Type
string
Description
Unique id of the Payment.
Name
chainId
Type
number
Description
Chain ID of the network where the recipient action was completed.
Name
txHash
Type
string
Description
Transaction hash of the recipient on-chain call on chainId.
Name
payment
Type
object
Description
The Payment object corresponding to this event.

EVENT

payment_completed

{
  "type": "payment_completed",
  "paymentId": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "chainId": 8453,
  "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
  "payment": {
    "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
    "status": "payment_completed",
    "createdAt": "1739554073",
    "display": {
      "intent": "Pay Daimoo",
      "paymentValue": "1.00",
      "currency": "USD"
    },
    "source": {
      "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
      "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
      "chainId": "10",
      "amountUnits": "1.00",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
    },
    "destination": {
      "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
      "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
      "chainId": "8453",
      "amountUnits": "1.00",
      "tokenSymbol": "DAI",
      "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "calldata": "0x"
    },
    "externalId": null,
    "metadata": null
  }
}

Payment bounced

Triggered when a Payment 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.

Name
type
Type
string
Description
Type of the event, in this case payment_bounced.
Name
paymentId
Type
string
Description
Unique id of the Payment.
Name
chainId
Type
number
Description
Chain ID of the network where the recipient action was completed.
Name
txHash
Type
string
Description
Transaction hash of the recipient on-chain call on chainId.
Name
payment
Type
object
Description
The Payment object corresponding to this event.

EVENT

payment_bounced

{
  "type": "payment_bounced",
  "paymentId": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
  "chainId": 8453,
  "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
  "payment": {
    "id": "7Tt3HUMmU83PPvd2djwcsHSZ8upMNW4sTL7a8eFQhWiQ",
    "status": "payment_bounced",
    "createdAt": "1739554073",
    "display": {
      "intent": "Pay Daimoo",
      "paymentValue": "1.00",
      "currency": "USD"
    },
    "source": {
      "payerAddress": "0xFBfa6A0D1F44b60d7CCA4b95d5a2CfB15246DB0D",
      "txHash": "0xf975e462c8191d18ef970579814ebf68c83c45b4fa8984184f744f739285133b",
      "chainId": "10",
      "amountUnits": "1.00",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
    },
    "destination": {
      "destinationAddress": "0x3a321372E8a9755cD2CA6114eB8dA32A14F8100b",
      "txHash": "0x8316f2dd90051333a6f879d7b15cacdf960535e56476a5300ad90c14377fa347",
      "chainId": "8453",
      "amountUnits": "1.00",
      "tokenSymbol": "DAI",
      "tokenAddress": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
      "calldata": "0x"
    },
    "externalId": null,
    "metadata": null
  }
}

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.