Last updated · May 9, 20265 min read

Webhooks

Receive real-time notifications when events happen at your store.

Available events

Event	Description
`card.activated`	A consumer activated a new card at your store.
`card.reloaded`	A consumer topped up an existing card.
`card.transferred_in`	Balance was transferred into your store from another store.
`card.transferred_out`	Balance was transferred out of your store to another store.
`card.balance_changed`	Any balance change on a card at your store.
`card.disabled`	A card at your store was permanently disabled.

Webhook payload

json

{
  "event": "card.activated",
  "timestamp": "2026-04-05T10:30:00Z",
  "data": {
    "cardUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amountCents": 5000,
    "currency": "USD",
    "newBalanceCents": 5000,
    "consumerEmail": "customer@example.com"
  }
}

Verifying webhooks

javascript

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Register a webhook

POST /api/v1/webhooks

Body parameters

urlrequired
string
Your endpoint URL. Must be HTTPS.
eventsrequired
string[]
Array of event types to subscribe to. See the table above.

bash

curl -X POST https://merchant.reloadcard.app/api/v1/webhooks \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/reloadcard",
    "events": ["card.activated", "card.reloaded", "card.disabled"]
  }'

Example response (201)

json

{
  "id": "wh_abc123",
  "url": "https://yoursite.com/webhooks/reloadcard",
  "events": ["card.activated", "card.reloaded", "card.disabled"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "created_at": "2026-04-08T10:00:00Z"
}

List webhooks

GET /api/v1/webhooks

bash

curl https://merchant.reloadcard.app/api/v1/webhooks \
  -H "Authorization: Bearer rc_live_your_key"

Update a webhook

PATCH /api/v1/webhooks/:id — update the URL, events, or active status. Only include the fields you want to change.

bash

curl -X PATCH https://merchant.reloadcard.app/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer rc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["card.activated", "card.reloaded", "card.transferred_in", "card.disabled"],
    "is_active": true
  }'

Delete a webhook

DELETE /api/v1/webhooks/:id

bash

curl -X DELETE https://merchant.reloadcard.app/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer rc_live_your_key"

Delivery details

HMAC-SHA256 signing — every request includes an X-ReloadCard-Signature header. Verify with your webhook secret.
10-second timeout — your endpoint must respond within 10 seconds with a 2xx status code, or the delivery is marked as failed.
Retry policy — failed deliveries are retried up to 3 times with exponential backoff. After 3 consecutive failures, the webhook is automatically disabled and you're notified by email.

Retry policy

Attempt	Delay
1st retry	~1 minute
2nd retry	~5 minutes
3rd retry	~30 minutes
After 3 failures	Webhook disabled · email sent

Re-enable a disabled webhook via PATCH with { "is_active": true } or from the merchant dashboard.