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

# Create Webhook

> Create a new webhook subscription in your workspace.

Requires an API key with `full_access` scope.

Creates a webhook that will receive HTTP POST requests whenever the specified events occur in your workspace. The response includes a `secret` that you should store safely for [verifying webhook signatures](/webhooks/verify-signatures). The secret is only shown once.

## Body

<ParamField body="name" type="string" required>
  Webhook name. 2 to 100 characters.
</ParamField>

<ParamField body="url" type="string" required>
  The HTTPS endpoint that will receive webhook deliveries. Must start with `https://`.
</ParamField>

<ParamField body="event_types" type="string[]" required>
  List of event types to subscribe to. Must include at least one of:

  `project.created`, `project.updated`, `project.deleted`, `job.created`, `job.updated`, `job.deleted`, `job_type.created`, `job_type.deleted`
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier of the newly created webhook.
</ResponseField>

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

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

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

<ResponseField name="status" type="string">
  Webhook status. Always `active` for new webhooks.
</ResponseField>

<ResponseField name="secret" type="string">
  The webhook signing secret, prefixed with `dbwhsec_`. Use this to [verify delivery signatures](/webhooks/verify-signatures).

  <Warning>
    This is the only time the secret will be returned. Store it securely.
  </Warning>
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp (milliseconds) when the webhook was created.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.dronebundle.com/v1/webhooks \
    -H "Authorization: Bearer v1_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Project notifications",
      "url": "https://hooks.example.com/dronebundle",
      "event_types": ["project.created", "project.updated", "job.created"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "019d5221-b413-71a9-a56b-f70bc91efe63",
    "name": "Project notifications",
    "url": "https://hooks.example.com/dronebundle",
    "event_types": ["project.created", "project.updated", "job.created"],
    "status": "active",
    "secret": "dbwhsec_f6c24a58cf36be393959ab854bc766942ed0bf5f830ca01eeecfe70c6bc0815e",
    "created": 1743400000000,
    "message": "Webhook created. This is the only time you will see the secret. Store it safely."
  }
  ```
</ResponseExample>

## Errors

**400 Bad Request** - Validation failed.

```json theme={null}
{
  "message": "name is required"
}
```

Other validation messages include:

* `name must be between 2 and 100 characters`
* `url is required`
* `url must start with https://`
* `event_types is required and must include at least one of: project.created, ...`
* `Invalid event type: {type}`