How webhooks work
Webhooks notify your server about order events so your team can update its own records and workflows. Tyga Pay sends a signed HTTPS POST to your endpoint; your customer's browser does not receive it.
- Tyga Pay records an order event. An active endpoint is needed to prepare a delivery.
- Tyga Pay sends a signed event to your endpoint. Your server verifies it, stores or queues it once, and returns a
2xxresponse. - Your system reads the latest order before acting. A webhook is a snapshot of a transition; later events or payment review can change the current state.
Webhooks are optional for order creation. Without an active endpoint, the order can still be created, but no delivery is prepared for your server.
For managers: order.created does not mean the customer paid. A payment event reports a change in payment status; it does not confirm a payout. “Delivered” means your endpoint returned 2xx, not that your team finished processing the order. A checkout redirect is not payment proof either.
Set up an endpoint
- Sign in to the developer portal and open the merchant workspace you want to configure.
- Open Webhooks, select Add webhook, choose the events your server needs, and save your server's public HTTPS URL. Active administrator and developer members can manage it. The portal may ask you to verify your passkey again.
- Copy the signing secret shown after first creation into your server's secret store. It is shown once and is separate from your merchant API key. If an existing endpoint has no secret available to copy, use Rotate secret to receive a new one.
- Use Send test webhook and check Last test plus Webhook activity. A test sends
webhook.testthrough the same signed delivery path; it does not create an order or prove payment processing.
Each webhook configuration has one destination and its own signing secret. If you configure more than one API environment, set up each destination separately, even when the URLs match.
Use an HTTPS URL that resolves to a public IPv4 address and accepts direct POST requests. Localhost, private addresses, IPv6-only destinations, custom ports, credentials and URL fragments are unsupported. Tyga Pay does not follow redirects.
Editing the URL, rotating the secret or disabling the endpoint changes its version. Pending deliveries for an older version are disabled instead of being sent to the new destination. Rotate only after your receiver can use the replacement secret. An already in-flight request might still carry the previous signature.
Events and payloads
order.created- A new order was created.
data.statusisopen; this event does not mean funds arrived. order.paid- Verified payment changed the payment state to
paid. It does not mean the merchant's Checkout wallet balance is available; availability follows a separately verified treasury sweep. A later review event can supersede this snapshot. order.payment_review_required- The payment state changed to
review_required, for example after a late, cancelled or revoked deposit. Pause fulfillment and inspect the current order. order.payment_partially_received- Another verified top-up arrived while the order was still below its payment threshold. Emitted for each increase.
order.payment_overpaid- The verified surplus increased, including its first appearance. The surplus is held separately from the merchant's Checkout wallet.
order.overpayment_resolution_recorded- A surplus resolution was recorded. An outcome of
refundedrequires a linked, independently verified completed refund. order.cancelled- An active order was cancelled. Cancellation does not return funds already received.
order.expired- The checkout deadline was observed while the order was unpaid or partially paid. Expiry does not return funds. A payment included on chain before the deadline may still be verified afterward and produce
order.paid. refund.created- A refund request was created and is awaiting customer confirmation.
data.statusisawaiting_customer_confirmation. refund.requested- The customer confirmed a return destination for a merchant refund request. Operations has not approved or transferred funds.
refund.approved- Operations approved the request and reserved the matching merchant or system-held funds.
refund.rejected- Operations rejected the request. Any prior reservation is released.
refund.processing- Operations recorded an externally executed transfer. Finality and exact transfer details are still being checked.
refund.completed- The recorded transfer was independently verified with the expected source, destination, token, amount and chain finality.
refund.failed- The recorded transfer was independently verified as failed. The reservation is released; request another refund if a return is still needed.
refund.cancelled- The request was cancelled before Operations approval. Any reserved request capacity is released.
refund.confirmation_expired- The customer did not confirm within seven days. Issue a new customer link to continue; each expiry produces its own event.
mandate.active- A subscription’s first payment activated it. See Subscriptions.
mandate.charge.succeeded- A subscription renewal or charge was paid. Includes
chargeIdand, for wallet charges,transactionHash. mandate.charge.failed- A renewal or charge attempt failed. Includes
chargeId,failureReasonand, for scheduled renewals,attempt. Further attempts may follow. mandate.reauthorization_required- The customer’s wallet spending limit for the subscription is used up or was removed.
mandate.revoked- The customer revoked the subscription on chain from their wallet.
mandate.cancelled- The subscription was cancelled by you, from the portal, or after its last renewal attempt was not paid.
mandate.expired- The subscription reached its end date.
webhook.test- A connection check sent only when you select Send test webhook. It has no order;
data.environmentidentifies the connection used for the test.
The original three order events remain selected on existing endpoints. New lifecycle events are individually selectable and opt in. Editing the selection applies to future events; it does not disable deliveries already queued. Events that occurred before a selection was added are not sent automatically.
{
"id": "0000000000000000000000000000000000000000000000000000000000000000",
"type": "order.paid",
"apiVersion": "v2",
"createdAt": "2026-09-25T10:00:00.000Z",
"data": {
"orderId": "00000000-0000-4000-8000-000000000001",
"merchantReference": "MERCHANT-ORDER-001",
"amountMinor": 100,
"currency": "USD",
"status": "paid",
"assetId": "USDC",
"networkId": "ethereum-sepolia",
"amountBaseUnits": "1000000",
"receivedBaseUnits": "1000000"
}
}Every event has a stable id, type, apiVersion: "v2", UTC createdAt, and data. Order events contain orderId, merchantReference, amountMinor in USD cents, currency: "USD", and status. For payment events, status is the payment state at that transition. It is not the order's lifecycle status.
Payment events can also include assetId, networkId, amountBaseUnits (expected token amount), receivedBaseUnits (credited token amount), overpaymentBaseUnits when nonzero, and reviewReason when present. Current review reasons are order_cancelled, deposit_revoked and late_or_missing_inclusion. Base-unit amounts are decimal strings in the token's smallest unit, not USD cents. Treat optional fields as optional.
The partial-payment and overpayment events include cumulative receivedBaseUnits, remainingBaseUnits and surplusBaseUnits, plus changeBaseUnits for this increase. order.paid still captures its original transition. Read the current order and payment history when you need the latest amount.
Refund events include refundId, purpose, refundAmountBaseUnits and the refund status. Order-value refunds also include refundAmountMinor in USD cents. Transfer events (refund.processing, refund.completed, refund.failed) include transferId and, when available, an explorerUrl. Approval and rejection events can include a merchantNote from Tyga Pay. Use refund reads for the current status.
Subscription events (mandate.*) carry the order fields of the order they relate to, plus mandateId and status: the agreement status, or succeeded / failed for mandate.charge.*. Read the agreement with GET /v2/mandates/{mandateId} for its current state.
Persist each event ID before processing it. Deliveries may repeat or arrive out of order, so read the current order or refund rather than assuming the most recently received event is the latest state. No wallet-balance event is sent.
Before you fulfil
An order.payment_review_required can follow order.paid for the same order. It's rare, but plan for it before you pack or ship.
deposit_revoked- Orders of $1,000 or less, paid in a single transfer on Ethereum or Polygon, are marked paid early, before the network finalises the transfer. If the transfer is dropped before then, the order moves to review. This can only happen within about 15 minutes of
order.paid. Treat the order as unpaid. late_or_missing_inclusion- The customer sent an extra transfer after the order expired. It can arrive at any time, but the original payment still counts, so it doesn't need to hold up fulfilment.
We recommend holding fulfilment for 30 minutes after order.paid, then checking that paymentStatus is still paid with GET /v2/orders/:orderId before you pack.
Verify signatures
Tyga Pay sends Content-Type: application/json, Tyga-Event-Id and Tyga-Signature. The event ID header matches the JSON id. The signature has the form t=<Unix seconds>,v1=<hex HMAC>. Compute HMAC-SHA256 over the exact raw request bytes prefixed with the timestamp and a period: <t>.<raw body>.
Verify before parsing or changing the body. Reject signatures outside a five-minute window and compare digests in constant time. The signature timestamp describes the send attempt; createdAt describes the event. Use the secret for that endpoint. Never send it to a browser, put it in a URL or log it.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verifyTygaWebhook(rawBody: Buffer, signatureHeader: string, secret: string): boolean {
const match = /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(signatureHeader)
if (!match || Buffer.byteLength(secret) < 32) return false
const timestamp = Number(match[1])
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false
const expected = createHmac('sha256', secret)
.update(`${timestamp}.`).update(rawBody).digest()
const received = Buffer.from(match[2], 'hex')
return timingSafeEqual(received, expected)
}Pass the unmodified request body as a Buffer and the Tyga-Signature header to this helper. Reject a failed check before handling the event. Then confirm Tyga-Event-Id equals the parsed id, and persist that ID with your business update so retries cannot apply the update twice.
Delivery and recovery
Return any 2xx status only after you have durably accepted the event. Non-2xx responses, redirects, network failures and the 20-second request timeout are treated as unsuccessful. Tyga Pay retries with backoff, up to ten send attempts; retry timing is not an exact schedule. Delivery can be repeated or arrive out of order, including after a timeout when your server did process the first attempt.
Reply quickly: verify the signature, save the event ID, return 2xx, then do slower work such as reading the order back or fulfilling it. The developer portal shows how long your endpoint took to answer each delivery, in orange from 10 seconds and red from 15 seconds. Investigate anything in the red, because it is close to timing out.
- Sending
pending - Queued, in flight or waiting for a retry. An event can remain here while delivery is still being attempted.
- Delivered
delivered - Your endpoint returned
2xx. Check your own processing separately. - Failed
failed - The send limit was reached without a
2xx. Fix the receiver, then select Retry webhook in the delivery details. Reconcile the order through the API as well. - Disabled
disabled - The endpoint was disabled or its version changed before delivery. These old deliveries are not sent to the replacement endpoint.
In portal Webhooks, the newest five deliveries appear first. Select Load 5 more to browse older deliveries, or search for an exact order ID, order reference or event ID. Select a delivery to inspect its attempts, last HTTP response and payload. Activity remains visible if the endpoint is later disabled.
A failed delivery can be retried from its details after an active endpoint is configured. The retry sends the original event ID and payload to the current endpoint and begins a new cycle of up to ten attempts. Your receiver must handle duplicates. A missing row does not prove that no order changed: if no active endpoint existed when the event was prepared, no delivery was created. A test can show Queued or Sending before its final result; refresh later if it is still in progress.
For each new event ID, verify and store it once, then retrieve the latest order with GET /v2/orders/:orderId using an orders_read key. Check paymentStatus before fulfillment; the order lifecycle status can still read open after payment. Cancelled orders return 404 from that lookup, while their payment history remains available for reconciliation. If a later review event arrives, stop automatic fulfillment and investigate. Keep your own recovery path for failed or missed notifications.