Events Reference

Morph Payments notifies your application of order lifecycle changes by sending an HTTP POST request to the webhook URL you configured. Each request delivers a single order status event as a JSON body.

Every request is signed. Before trusting a payload, verify the signature as described in Signature Verification.

Delivery

Property	Value
Method	`POST`
Content-Type	`application/json`
Target	The webhook URL registered for your merchant account
Success	Your endpoint returns any `2xx` status code
Failure	Any non-`2xx` response, timeout, or connection error

Respond with a 2xx status code as soon as you have accepted the event. Perform any slow processing asynchronously — a slow response is treated as a failed delivery and will be retried.

Event types

The event type is carried in the status field of the payload.

`status`	Meaning
`success`	The order was paid successfully. `paid_at` is set.
`failed`	The order failed.
`expired`	The order expired before it was paid.

Payload

The webhook body is a JSON object with the following fields.

Field	Type	Description
`event_id`	string	Unique identifier for this event. Use it for idempotency (see below).
`platform_order_id`	string	Morph Payments order identifier.
`merchant_id`	string	Your merchant identifier.
`payee_order_id`	string	Your own order reference supplied when the order was created.
`status`	string	Order status: `success`, `failed`, or `expired`.
`amount`	string	Order amount as a decimal string. Never parse as a float.
`pay_token`	string	Token used for payment.
`pay_network`	string	Network the payment was made on.
`tx_hash`	string	On-chain transaction hash.
`source_type`	string	Origin of the order.
`source_id`	string	Identifier within the source.
`receiving_network`	string	Network funds were received on.
`receiving_address`	string	Address funds were received at.
`receiving_token_address`	string	Token contract address for the received funds.
`payer_address`	string	Address that paid the order.
`paid_at`	integer	Payment time in Unix milliseconds. `0` when `status` is not `success`.
`event_time`	integer	Time the event occurred, in Unix milliseconds.
`created_at`	integer	Order creation time, in Unix milliseconds.
`updated_at`	integer	Last update time, in Unix milliseconds.

note

Amounts are decimal strings and timestamps are integer Unix milliseconds. Always handle amount as a string to avoid precision loss.

Example

{
  "event_id": "evt_9f2c1a7b3d",
  "platform_order_id": "ord_20260715_0001",
  "merchant_id": "mch_123456",
  "payee_order_id": "your-order-42",
  "status": "success",
  "amount": "12.500000",
  "pay_token": "USDC",
  "pay_network": "morph",
  "tx_hash": "0xabc123...",
  "source_type": "checkout",
  "source_id": "chk_001",
  "receiving_network": "morph",
  "receiving_address": "0xReceiver...",
  "receiving_token_address": "0xToken...",
  "payer_address": "0xPayer...",
  "paid_at": 1752566400000,
  "event_time": 1752566400500,
  "created_at": 1752566100000,
  "updated_at": 1752566400500
}

Idempotency

The same event may be delivered more than once — for example when your endpoint was slow to respond and a retry was triggered before your 2xx was received.

Treat event_id as the idempotency key. Record the event_id values you have already processed and ignore duplicates.

Retries

If a delivery does not receive a 2xx response, Morph Payments retries the event using an exponential backoff schedule. There are up to 5 retry attempts:

Retry	Wait after previous attempt
1	1 minute
2	5 minutes
3	15 minutes
4	60 minutes
5	240 minutes

After all retries are exhausted without a 2xx response, the event is marked as undeliverable and no further attempts are made.