Webhook events

Every event type with its payload shape.

Webhook endpoints receive signed event deliveries. This page is the reference for registration and every event type.

Register an endpoint#

bash

curl -s -X POST "$JUICEPAY_URL/v1/webhook_endpoints" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{
    "url": "https://api.example.com/webhooks/juicepay",
    "enabled_events": ["payment_intent.succeeded", "payout.settled"],
    "description": "Production consumer"
  }'

The response includes the signing secret, shown only once.

json

{
  "id": "we_5mK2",
  "url": "https://api.example.com/webhooks/juicepay",
  "status": "enabled",
  "enabled_events": ["payment_intent.succeeded", "payout.settled"],
  "secret": "whsec_4mW8bZ2nHq6Yc1Pd9fKxQ7mLpVn8Rt"
}

Use "enabled_events": ["*"] to receive everything. Subscribe narrowly in production — broad subscriptions make it easy to fall behind during batch runs.

Delivery headers#

Header	Value
`JuicePay-Signature`	`t=<unix>,v1=<hmac-sha256>`
`JuicePay-Event`	Event type
`JuicePay-Delivery`	Unique delivery ID, useful for log correlation
`JuicePay-Attempt`	1-based attempt counter

Envelope#

json

{
  "id": "evt_2xNpRt8kL3mQ",
  "type": "payment_intent.succeeded",
  "created": "2026-08-19T09:14:02Z",
  "livemode": true,
  "data": {
    "object": {
      "id": "pi_9fK2xQ",
      "status": "succeeded",
      "amount": "4250.00",
      "asset": "USDC",
      "amount_received": "4250.000000",
      "reference": "INV-2291"
    }
  },
  "request": { "id": "req_8kL3mQ2xNp", "idempotency_key": "order:ord_8812:intent" }
}

Event catalogue#

Event	Resource	Notes
`payment_intent.processing`	Payment intent	Seen onchain, not final.
`payment_intent.succeeded`	Payment intent	Terminal.
`payment_intent.partially_paid`	Payment intent	Outside tolerance.
`payment_intent.expired`	Payment intent	Terminal.
`payment_intent.reverted`	Payment intent	Reorg removed a prior success.
`payment_intent.unsupported_chain`	Payment intent	No credit applied.
`payout.created`	Payout	Accepted.
`payout.leg.broadcast`	Payout leg	Reached the network.
`payout.settled`	Payout	Terminal.
`payout.partially_settled`	Payout	Terminal, partial.
`payout.failed`	Payout	Terminal.
`payout.batch.completed`	Batch	All legs terminal.
`swap.executing`	Swap	Broadcast.
`swap.settled`	Swap	Credited.
`swap.failed`	Swap	Not completed.
`limit_order.working`	Limit order	Watching venues.
`limit_order.partially_filled`	Limit order	Tranche filled.
`limit_order.filled`	Limit order	Fully filled.
`limit_order.canceled`	Limit order	Cancelled or expired.
`balance.updated`	Balance	Any change; includes `as_of`.
`recipient.screening_updated`	Recipient	Screening verdict changed.

Retries and response handling#

Deliveries are attempted for up to 24 hours with exponential backoff. Any 2xx acknowledges the event. 410 Gone disables the endpoint permanently.

export async function POST(request: Request) {
  const raw = await request.text();
  const event = juicepay.webhooks.constructEvent(
    raw,
    request.headers.get("juicepay-signature")!,
    process.env.JUICEPAY_WEBHOOK_SECRET!,
  );

  await enqueue(event); // fast, durable
  return Response.json({ received: true });
}

Replay#

bash

curl -s -X POST "$JUICEPAY_URL/v1/webhook_endpoints/we_5mK2/replay" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{ "from": "2026-08-18T00:00:00Z", "to": "2026-08-19T00:00:00Z" }'

Replayed events keep their original IDs, so a consumer that deduplicates on event ID will correctly treat them as already processed.

Delivery log#

bash

curl -s "$JUICEPAY_URL/v1/webhook_endpoints/we_5mK2/deliveries?limit=20" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Each entry records the response status, latency, and attempt number — enough to diagnose a misbehaving consumer without guessing.