Events and payload

Solverr sends a signed POST request to your webhook URL whenever an invoice, refund, payout, subscription or support case changes. Use these events to mark orders as paid on your server without polling. Never fulfill orders from browser events.

Set up your endpointCopy Anchor Link

Each business has one webhook URL and one signing secret. Only the owner can change them.

1. Open Dashboard → Developers and find the Webhook card.
2. In Endpoint URL (https), enter your endpoint URL, for example https://shop.example/webhooks/solverr, and select Save.
3. Store the signing secret, which starts with whsec_ and is shown once, on the server that receives events, for example as SOLVERR_WEBHOOK_SECRET.
4. Select Send ping event to check that your endpoint receives and verifies events (see Test your webhook endpoint).

To turn webhooks off, clear the URL, select Turn webhooks off, then select Turn off to confirm. While no URL is saved, events are not queued and are never sent later.

PayloadCopy Anchor Link

Every event is a JSON object with the same five fields:

{
  "id": "evt_5tR8mW2xQpL7vN3kB9sZ",
  "type": "invoice.paid",
  "mode": "live",
  "created_at": "2026-11-05T12:03:41.000Z",
  "data": {
    "invoice": { "id": "inv_7h3K9dWq2LmN4pRt6vXy", "object": "invoice", "status": "paid", "order_id": "1042" },
    "payment": { "id": "quo_4kT9mW2xQpL7vN3rB8sZ", "object": "payment", "status": "success" }
  }
}

The example shortens invoice and payment. Real events carry the full invoice and payment objects.

Request headersCopy Anchor Link

Solverr signs events the Standard Webhooks way, so any Standard Webhooks library can verify them.

Verify signatures shows how to check them.

Event typesCopy Anchor Link

Which events to handleCopy Anchor Link

For a shop, invoice.paid is the event that matters: mark the order paid when it arrives. These cases need extra care:

• invoice.paid with late: true. The customer paid to an address that was already replaced or expired, but the money still reached you. Complete the order or refund it.
• invoice.expired, then invoice.paid. A late payment can still arrive within 24 hours after expiry. Do not treat invoice.expired as final if you can still fulfill the order.
• invoice.detected is not final. If that payment is returned or fails, the invoice goes back to where the customer's newest payment attempt stands. When that attempt is still waiting for a payment, no event is sent until the next change. When it already ended, or the invoice's lifetime has passed, you get that status's event: invoice.underpaid, invoice.refunded, invoice.failed or invoice.expired.
• invoice.extra_payment. The customer paid twice. Return the second payment with Refund this extra payment on the invoice's page in Dashboard → Payments (see Refunds).
• invoice.underpaid and invoice.refunded. No money reached you. After invoice.underpaid, NEAR Intents returns the payment to the customer, and invoice.refunded follows. The customer can then try again from the checkout page while at least 2 minutes of the invoice's lifetime remain.
• No invoice.expired after underpaid, refunded or failed. An invoice that ended in one of these statuses keeps it after expires_at. Treat it as unpaid once expires_at has passed, unless a late invoice.paid arrives.

Good practiceCopy Anchor Link

• The same event can arrive more than once. Store each id you handled and skip repeats.
• Events can arrive out of order when a retry is involved. Trust the status in the event's invoice, not the order of arrival.
• Answer with any 2xx status within 10 seconds, and do slow work after you answer.