Getting started with webhooks

Webhooks push notifications to your endpoint as events happen, so you do not have to poll for updates. Because charges and payouts settle asynchronously, webhooks are the primary way you learn that money actually moved.

Set up a webhook

Go to app.zerocash.tech.

Open Webhooks

Find the Webhooks section in the sidebar.

Add your URL

Verify signatures

Before trusting any payload, check the signature. See Webhook secrets.

You can read back your currently configured webhook URLs for both environments through Get User.

Delivery behaviour

	Behaviour
Timeout	If your server does not respond within 15 seconds, the attempt is marked failed.
Retries	Failed webhooks are retried up to 3 times with exponential backoff.
Backoff	1st retry after 5s · 2nd after 15s · 3rd after 45s

Keep your handler lightweight. Acknowledge with a 2xx immediately and offload database writes, notifications, and other slow work to a background job. Doing that work inline is the usual cause of the 15-second timeout — and a timeout means a retry, which means you may process the same event twice.

Writing a reliable handler

Respond fast, process later

Validate the signature, enqueue the payload, return 200. Anything else belongs in a worker.

app.post("/webhooks/zerocash", (req, res) => {
  if (!isValidSignature(req)) return res.status(401).end();

  queue.push(req.body);   // hand off
  res.status(200).end();  // acknowledge within 15s
});

Make processing idempotent

Retries mean the same event can arrive more than once, and events can arrive out of order. Key your processing on transactionId (or your externalReference) and ignore an event that would move a transaction backwards from a terminal state.

Never trust the payload alone for high-value actions

For anything irreversible, confirm against Get Transaction before releasing value.

Return 2xx even for events you ignore

A non-2xx tells Zerocash the delivery failed and triggers a retry. If you receive an event type you do not handle, acknowledge it anyway.

Inspecting and replaying deliveries

Task	Endpoint
List delivery attempts	Get Webhooks
Inspect one delivery	Get Webhook
Retry a delivery	Resend Webhook
Fire a test event (sandbox)	Simulate Webhook

Simulate Webhook lets you exercise your handler against every event shape without running real transactions — useful for testing failure paths that are hard to trigger on demand.

Webhook secrets

Verify that a request genuinely came from Zerocash.

Event types & structures

The base envelope, event names, and transaction types.

External accounts Webhook secrets

⌘I

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Getting started with webhooks

Set up a webhook

Delivery behaviour

Writing a reliable handler

Inspecting and replaying deliveries

Next

Webhook secrets

Event types & structures

​Set up a webhook

​Delivery behaviour

​Writing a reliable handler

​Inspecting and replaying deliveries

​Next

Webhook secrets

Event types & structures

Set up a webhook

Delivery behaviour

Writing a reliable handler

Inspecting and replaying deliveries

Next