# Create a webhook destination

> **POST** `https://api.us.nylas.com/v3/webhooks`

Source: https://developer.nylas.com/docs/reference/api/webhook-notifications/post-webhook-destinations/

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.

**Authentication:** NYLAS_API_KEY

## Request body

Destination definition

Content-Type: application/json

- `description` (string) - A human-readable description of the webhook destination.
- `trigger_types` (array) **(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` (array) - 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`.

## Responses

### 200 - Returns the new Destination

- `data` (object)
  - `id` (string) - A unique identifier for the webhook destination.
  - `description` (string) - A human-readable description of the webhook destination.
  - `trigger_types` (array) - 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` (string) - 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` (array) - 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.

### 400 - Destination not created

- `error` (object)
  - `type` (string) - An alphanumeric code that represents the error type.
  - `message` (string) - A human-readable message with details about the error.
- `request_id` (string) - The ID of the request.

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/webhooks/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "trigger_types": [
      "grant.created",
      "grant.deleted",
      "grant.expired"
    ],
    "description": "local",
    "webhook_url": "<WEBHOOK_URL>",
    "notification_email_addresses": [
      "leyah@example.com",
      "nyla@example.com"
    ]
  }'
```

### Node.js SDK

```javascript
import Nylas, { WebhookTriggers } from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

const createWebhook = async () => {
  try {
    const webhook = await nylas.webhooks.create({
      requestBody: {
        triggerTypes: [WebhookTriggers.EventCreated],
        webhookUrl: "<WEBHOOK_URL>",
        description: "My first webhook",
        notificationEmailAddresses: ["<EMAIL_ADDRESS>"],
      },
    });

    console.log("Webhook created:", webhook);
  } catch (error) {
    console.error("Error creating webhook:", error);
  }
};

createWebhook();

```

### Python SDK

```python
from nylas import Client
from nylas.models.webhooks import WebhookTriggers

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>",
)

webhook = nylas.webhooks.create(
    request_body={
        "trigger_types": [WebhookTriggers.EVENT_CREATED],
        "webhook_url": "<WEBHOOK_URL>",
        "description": "My first webhook",
        "notification_email_addresses": ["<EMAIL_ADDRESS>"],
    }
)

print(webhook)

```

### Ruby SDK

```ruby
require 'nylas'

nylas = Nylas::Client.new(api_key: "<NYLAS_API_KEY>")

request_body = {
  trigger_types: [Nylas::WebhookTrigger::EVENT_CREATED],
  webhook_url: "<WEBHOOK_URL>",
  description: 'My first webhook',
  notification_email_addresses: ["<EMAIL_ADDRESS>"]
}

begin
  webhook, _request_id = nylas.webhooks.create(request_body: request_body)

  puts "Webhook created: #{webhook}"
rescue Nylas::NylasApiError => e
  puts "Error creating webhook: #{e.message}"
end

```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;

public class webhooks {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    List<WebhookTriggers> triggers = new ArrayList<>();
    triggers.add(WebhookTriggers.EVENT_CREATED);

    CreateWebhookRequest webhookRequest = new CreateWebhookRequest(
        triggers,
        "<WEBHOOK_URL>",
        "My first webhook",
        List.of("<EMAIL_ADDRESS>"));

    try {
      Response<WebhookWithSecret> webhook = nylas.webhooks().create(webhookRequest);

      System.out.println(webhook.getData());
    } catch (Exception e) {
      System.out.println("Error: " + e);
    }
  }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>){
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val triggersList: List<WebhookTriggers> = listOf(WebhookTriggers.EVENT_CREATED)

  val webhookRequest: CreateWebhookRequest = CreateWebhookRequest(
      triggersList,
      "<WEBHOOK_URL>",
      "My first webhook",
      listOf("<EMAIL_ADDRESS>"))

  try {
    val webhook: Response<WebhookWithSecret> = nylas.webhooks().create(webhookRequest)

    println(webhook.data)
  } catch(exception : Exception) {
    println("Error :$exception")
  }
}

```