Skip to main content

​
Webhooks

Get notified in real-time when staging completes, images are claimed, or credits run low.

​
Setup

Configure a webhook URL for your API key: 
curl -X PUT .../api/v1/keys/12/webhook \
  -H "Authorization: Bearer <firebase-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/staging",
    "enabled": true
  }'

​
Events

EventTrigger
staging.completeImage staged successfully
claim.redeemedAgent claimed images
credits.lowBalance below threshold
auto_topup.successAuto top-up succeeded
auto_topup.failedAuto top-up failed
test.pingManual test

​
Payload format

{
  "event": "staging.complete",
  "timestamp": "2026-03-25T14:30:00Z",
  "data": {
    "image_url": "https://...",
    "claim_code": "SS-7X9K2M",
    "style": "modern",
    "room_type": "living_room",
    "credits_used": 1,
    "credits_remaining": 46
  }
}

​
Verifying signatures

Every webhook includes a X-Webhook-Signature header. Verify it with HMAC-SHA256: 
import hmac
import hashlib

def verify_webhook(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

​
Testing

Send a test ping to verify your endpoint: 
curl -X POST .../api/v1/keys/12/webhook/test \
  -H "Authorization: Bearer <firebase-token>"
Use webhook.site for testing during development.