> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stagingspaces.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time notifications for staging events

# 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:

```bash theme={null}
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

| Event                | Trigger                   |
| -------------------- | ------------------------- |
| `staging.complete`   | Image staged successfully |
| `claim.redeemed`     | Agent claimed images      |
| `credits.low`        | Balance below threshold   |
| `auto_topup.success` | Auto top-up succeeded     |
| `auto_topup.failed`  | Auto top-up failed        |
| `test.ping`          | Manual test               |

## Payload format

```json theme={null}
{
  "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:

```python theme={null}
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)
```

```javascript theme={null}
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:

```bash theme={null}
curl -X POST .../api/v1/keys/12/webhook/test \
  -H "Authorization: Bearer <firebase-token>"
```

<Tip>
  Use [webhook.site](https://webhook.site) for testing during development.
</Tip>