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

# Create Webhook

> Register a new webhook endpoint for the current workspace.

## Authentication

Requires an API key in the `Authorization` header.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField body="url" type="string" required>
  The HTTPS URL to receive webhook deliveries.
</ParamField>

<ParamField body="events" type="string[]" required>
  List of event types to subscribe to. At least one event is required.

  Valid events: `lookup.completed`, `apikey.created`, `apikey.revoked`, `credits.low`, `credits.exhausted`
</ParamField>

<ParamField body="description" type="string">
  Optional description for the webhook.
</ParamField>

### Example request

```bash theme={"dark"}
curl -X POST https://encrata.com/api/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["lookup.completed", "apikey.created"],
    "description": "Production webhook"
  }'
```

## Response

Returns the created webhook object, including the signing secret.

<ResponseField name="id" type="string">
  Unique webhook identifier (UUID).
</ResponseField>

<ResponseField name="url" type="string">
  The registered webhook URL.
</ResponseField>

<ResponseField name="secret" type="string">
  The HMAC-SHA256 signing secret. **Only returned at creation time** — store it securely.
</ResponseField>

<ResponseField name="events" type="string[]">
  Subscribed event types.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the webhook is active (defaults to `true`).
</ResponseField>

<ResponseField name="description" type="string">
  Webhook description.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

### Example response

```json theme={"dark"}
{
  "id": "360cb300-d885-4c18-af2c-d259f936bb38",
  "workspace_id": "51cdc9d9-203c-4345-b06d-222b560460aa",
  "url": "https://example.com/webhook",
  "secret": "whsec_6cce5d5445b12e649ce9e715a2ef4addc9117d6bf3013a0f388997ed20711b1c",
  "events": ["lookup.completed", "apikey.created"],
  "is_active": true,
  "description": "Production webhook",
  "created_by": "e861d7cb-1d7f-48d9-ab13-9af06a4055cf",
  "created_at": "2026-05-02T12:00:00Z",
  "updated_at": "2026-05-02T12:00:00Z"
}
```

<Warning>
  The `secret` is only returned when you create the webhook. Store it securely — you'll need it to [verify webhook signatures](/webhooks#verifying-signatures).
</Warning>