A webhook is how your app finds out about new email or calendar changes without asking. Instead of polling for "anything new yet?", you register a URL and Nylas pushes events to it as they happen. But setting one up correctly is more than posting a URL: your endpoint has to answer a challenge before the webhook activates, you get a signing secret exactly once, and you should verify a signature on every delivery so you don't process spoofed events. Get those three wrong and the webhook never turns on or your handler trusts forged data. This post sets up a webhook properly with the API and the CLI.
It's a worked use case rather than an endpoint tour, covering webhooks from two angles: the HTTP API your backend calls and the nylas CLI for creating, testing, and receiving them. I work on the CLI, so the commands below are the ones I reach for when wiring up notifications.
Create a webhook
You register a webhook with a POST /v3/webhooks request, and the two required fields are webhook_url, where Nylas sends notifications, and trigger_types, the array of events you want delivered. An optional description labels it and notification_email_addresses gets alerts about the webhook's health, like when it's failing.
