# billing.status_changed

> Sent when your organization's billing status changes, including whether it is accepting traffic. Live endpoints only.

Last updated: 2026-09-17

```http
POST https://your-server.example.com/webhooks/fingerly
```

Authentication: Signed by Fingerly (`x-fingerly-signature`)

Sent when your organization's billing status changes. Only endpoints listening to the `live` environment can subscribe.

> **Note:** Verify the signature before you parse the body, and answer `2xx` within 10 seconds. See [webhooks](https://docs.fingerly.io/docs/webhooks#verify-the-signature).

## Body

- `id` (string): The event's ID, a UUIDv7. The same on every retry: deduplicate on it. Also sent as `X-Fingerly-Event-ID`.
- `type` (string): Always `billing.status_changed`.
- `version` (integer): The envelope version, `1`.
- `organization_id` (string): Your organization.
- `environment` (string): `live` for production traffic, `test` for staging and development.
- `created_at` (string): When the underlying fact happened, RFC 3339 in UTC. Not when it was delivered.
- `data` (object): The change.
  - `previous_status` (string): The status before the change.
  - `current_status` (string): The status now.
  - `accepting_traffic` (boolean): Whether identifications are accepted in the current status.
  - `blocked_reason` (string | null): Why the organization is blocked, when it is. `null` otherwise.

## Statuses

| Status | Accepts traffic | Meaning |
| --- | --- | --- |
| `free` | Yes | No payment method on file. Traffic is paid from credit. |
| `active` | Yes | A payment method is on file. |
| `past_due` | Yes | A payment failed. Update the payment method before the account is blocked. |
| `blocked` | No | Identify requests are refused with `402 billing_blocked`. |

## Headers

```http Headers
POST /webhooks/fingerly HTTP/1.1
Content-Type: application/json
User-Agent: Fingerly-Webhooks/1.0
X-Fingerly-Event-ID: 01a0a851-0c4e-7f23-b8d1-6e2f94c0a7b5
X-Fingerly-Event-Type: billing.status_changed
X-Fingerly-Timestamp: 1789551672
X-Fingerly-Signature: sha256=6f1c0a3e9b…
```

## Payload

```json Body
{
  "id": "01a0a851-0c4e-7f23-b8d1-6e2f94c0a7b5",
  "type": "billing.status_changed",
  "version": 1,
  "organization_id": "01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37",
  "environment": "live",
  "created_at": "2026-09-16T09:41:12Z",
  "data": {
    "previous_status": "free",
    "current_status": "active",
    "accepting_traffic": true,
    "blocked_reason": null
  }
}
```