---
title: "Create a webhook destination"
method: POST
path: "/v3/webhooks"
tags: ["Webhook Notifications"]
---

# Create a webhook destination

`POST /v3/webhooks`

Creates a webhook destination with the specified URL and list of trigger types.

### Webhook destinations and retry logic

You should limit the number of webhook destinations you have for each trigger type. When Nylas
retries a webhook, the retry goes to all the destinations for that trigger type. This can result
in _a lot_ of notifications.

Some webhook testing tools rate-limit or block you if your endpoint generates too much traffic.
Nylas blocks Ngrok connections for this reason.

### Webhook notification header

Every webhook notification Nylas sends includes the `x-nylas-signature` header. If you're using
the Nylas SDKs, you might see `X-Nylas-Signature` instead.

## Request body

- DestinationInputPayload
  - `description` string — A human-readable description of the webhook destination.
  - `trigger_types` string[], required — The event that triggers the notification. See the [notification schemas](/docs/reference/notifications/) for details about each trigger type. See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/), [Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references for information on how to trigger each event type.
  - `webhook_url` string, required — The URL to send webhooks to.
  - `notification_email_addresses` string[] — The email addresses that Nylas notifies when a webhook is down for a while. See [Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for details.
  - `compressed_delivery` boolean — If `true`, Nylas compresses notification payloads using gzip before delivering them. Nylas adds the `Content-Encoding: gzip` header to the request. Default is `false`.

## Response `200`

Webhook Destination Created

- object
  - `data` object
    - `id` string — A unique identifier for the webhook destination.
    - `description` string — A human-readable description of the webhook destination.
    - `trigger_types` string[] — The event that triggers the notification. See the [notification schemas](/docs/reference/notifications/) for details about each trigger type. See the [Grants](/docs/reference/api/manage-grants/), [Calendar](/docs/reference/api/calendar/), [Events](/docs/reference/api/events/), and [Messages](/docs/reference/api/messages/) references for information on how to trigger each event type.
    - `webhook_url` string — The URL to send webhooks to.
    - `webhook_secret` string — A secret value used to encode the `x-nylas-signature` header on webhook requests.
    - `status` 'active' — The status of the new destination. This will always be "active" if Nylas successfully created the destination. If you need to pause the destination, use the [Update webhook destination](#put-/v3/webhooks/-id-) method to change the status to `pause`.
    - `notification_email_addresses` string[] — The email addresses that Nylas notifies when a webhook is down for a while. See [Failing and failed webhooks](/docs/v3/notifications/#failing-and-failed-webhooks) for details.
    - `compressed_delivery` boolean — If `true`, Nylas compresses notification payloads using gzip before delivering them.
  - `request_id` string — The request ID for each request.

## Other responses

- `400` — Destination not created

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)