Skip to main content
A webhook is how Minisend tells your server what happened without you having to ask. The moment a customer’s deposit shows up, and again once it actually settles, Minisend sends a signed POST to a URL you configure. You never have to poll for it.
Off-ramp orders, onramp orders, and the Wallet API each emit their own event namespace (offramp.*, onramp.*, wallet.*) to the same URL, signed the same way. This page focuses on checkout, since that’s what most integrations start with.

​
Setup

1

Add your endpoint

Dashboard → Webhooks. Paste your HTTPS URL, something like https://yourbusiness.com/webhooks/minisend, and save.
2

Copy your secret

Generated automatically the first time you land on that page, and shown once. You’ll use it to verify every incoming signature. See Verification.
3

Send yourself a test event

The same page has a Send test button, so you can confirm your signature check actually works before a real payment ever runs through it.
Always verify X-Minisend-Signature before acting on a payload. See Verification.

​
What fires, and when

A checkout session can produce up to five events on its way through, in order. First checkout.pending, the moment a deposit is seen and starts processing, not a confirmation. Then either checkout.completed or checkout.failed, or checkout.expired if nothing ever showed up. If you’re settling in USDC on a chain other than Base, one more can follow once your money finishes moving: checkout.forwarded. Two further events exist for the case where the customer’s payment already succeeded, but something on Minisend’s side needs a hand: settlement.forward_failed and settlement.swap_failed. Both mean the money is safe, just stuck in transit rather than lost. Full payloads for all seven events are on the Events page.
checkout.pending is not a confirmation. Use it to show a customer “we’ve seen your payment, hang on”, never to release goods.

​
Headers

Every delivery, for any event, carries these three: Checkout and settlement deliveries (the checkout.* and settlement.* events) carry three more, added for stronger replay protection and cleaner deduplication:
X-Minisend-Event-Id identifies a delivery, not a payment. The same logical event, checkout.completed for one session, say, can be sent more than once from different internal paths, each getting its own id. If you’re deduplicating to avoid double-fulfilling an order, key on (session_id, event) from the payload body instead of the header. See Events for the full explanation.
Your endpoint has 10 seconds to answer with a 2xx. Anything else, a timeout, a 4xx, a 5xx, counts as a failure and schedules a retry.

​
Retries

A failed delivery is retried on this schedule: Eight attempts spread across roughly 33 hours, so a short outage on your end doesn’t cost you the event. If your endpoint is still down after the last attempt, the delivery is marked failed and Minisend stops trying on its own.

​
Replay

Dashboard → Webhooks lists every delivery with its status and response. If you need to catch up on one that failed, replaying it resends the exact same bytes with a fresh timestamp and signature, under the same event id, so a correctly-built receiver treats it as the retry it is rather than a new event.
Five failed deliveries in a row and Minisend flags your endpoint as down, both in a banner on that page and internally. Fix your endpoint, then replay what was missed instead of waiting out the full retry schedule.