# identification.refused

> Sent when an identify request is refused: an expired or revoked key, an origin that is not allowed, billing, rate limiting or no credit.

Last updated: 2026-09-17

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

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

Sent for each identify request Fingerly refuses for a reason you can fix. Visitors whose requests are refused are not identified, so this is the event to alert on.

> **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 `identification.refused`.
- `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 refusal.
  - `request_id` (string): An ID for the refused request.
  - `sdk_key_id` (string): The key that was used.
  - `reason` (string): Why it was refused. See below.
  - `status` (integer): The HTTP status the client received.
  - `retry_after_seconds` (integer): For `rate_limited`: seconds until the client may retry. Omitted otherwise.

## Reasons

| `reason` | `status` | What to do |
| --- | --- | --- |
| `expired_key` | `401` | Issue a new key and deploy it. |
| `revoked_key` | `401` | A revoked key is still in use somewhere. Deploy its replacement. |
| `origin_not_allowed` | `401` | Add the site to the key's allowed origins, or find who is using your key. |
| `billing_blocked` | `402` | Resolve billing in the dashboard. |
| `no_credit` | `402` | Add funds, or turn on auto top-up. |
| `rate_limited` | `429` | Traffic exceeded your rate limit. Contact support if it is expected. |

> **Note:** Requests with a key Fingerly does not recognise at all are not attributable to an organization, so they send no webhook.

## 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: identification.refused
X-Fingerly-Timestamp: 1789551672
X-Fingerly-Signature: sha256=6f1c0a3e9b…
```

## Payload

```json origin_not_allowed
{
  "id": "01a0a851-0c4e-7f23-b8d1-6e2f94c0a7b5",
  "type": "identification.refused",
  "version": 1,
  "organization_id": "01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37",
  "environment": "live",
  "created_at": "2026-09-16T09:41:12Z",
  "data": {
    "request_id": "01a0a852-77d0-7b1c-a3e4-5f60718293a4",
    "sdk_key_id": "01a0a7f3-9e05-7a61-b4c7-2d8e0f3a6b19",
    "reason": "origin_not_allowed",
    "status": 401
  }
}
```

```json rate_limited
{
  "id": "01a0a851-0c4e-7f23-b8d1-6e2f94c0a7b5",
  "type": "identification.refused",
  "version": 1,
  "organization_id": "01a0a7f2-3c18-7b40-8d2e-5f6a9b1c0d37",
  "environment": "live",
  "created_at": "2026-09-16T09:41:12Z",
  "data": {
    "request_id": "01a0a852-77d0-7b1c-a3e4-5f60718293a5",
    "sdk_key_id": "01a0a7f3-9e05-7a61-b4c7-2d8e0f3a6b19",
    "reason": "rate_limited",
    "status": 429,
    "retry_after_seconds": 2
  }
}
```