标签：#webhooks

A webhook endpoint is a public URL sitting on the internet, and anything on the internet can send it a POST . If your app acts on whatever lands there, an attacker who guesses the URL can forge events: fake an inbound email, trigger a workflow, or feed your system garbage. The fix is to confirm two things before you trust a request, that you own the endpoint and that Nylas actually sent the payload, and both are built into how webhooks work. This post covers verifying webhooks from two angles: the HTTP mechanics your endpoint implements, and the nylas CLI for testing a signature without standing up a server. I work on the CLI, so the terminal commands below are the ones I reach for when I'm debugging a signature mismatch. Two layers of webhook trust There are two separate checks, and they happen at different times. The first is a one-time endpoint challenge: when you register or activate a webhook, Nylas sends your URL a request with a challenge value you echo back, proving you control the endpoint. The second runs on every notification afterward: each delivery carries a cryptographic signature you verify against a shared secret, proving the payload is genuine and wasn't tampered with. You need both because they defend against different things. The challenge stops you from accidentally registering an endpoint you don't own and confirms the URL is live. The signature stops anyone else from posting forged events to that URL once it's known. Skip the signature check and your public endpoint will trust any POST that reaches it, which is the most common webhook security mistake. Pass the endpoint challenge The first time you set up a webhook or flip one to active , Nylas sends a GET request to your endpoint with a challenge query parameter. Your endpoint has to return the exact value of that challenge in the body of a 200 OK response, within 10 seconds, or the webhook won't verify. It's a quick handshake that proves the URL is yours and reachable. // Express: echo the ch

If your integration polls Nylas every minute to check for new email, you're doing too much work and still getting stale data. Polling is a tax: you burn rate limit on requests that mostly return nothing, and a message that arrives at 12:00:05 doesn't reach your app until the next poll. Webhooks flip that around. Nylas pushes a notification to your endpoint the moment something happens — a message arrives, an event changes, a contact is created — and your app reacts in real time. This post walks the webhook surface from both sides: the HTTP API that registers and manages webhooks, and the Nylas CLI , which has genuinely useful tooling for the part everyone gets stuck on — verifying signatures and testing webhooks against local code. I work on the CLI, so the terminal commands below are the ones I run when I'm wiring up a webhook receiver. Triggers and destinations A webhook has two halves: the trigger types it listens for and the destination URL it pushes to. Trigger types are dotted event names like message.created , event.updated , and contact.created , grouped into categories — grant, message, thread, event, contact, calendar, folder, and notetaker. You subscribe one destination to as many triggers as you want. The CLI lists every available trigger so you don't have to guess the names: # All trigger types nylas webhook triggers # Only message-related triggers nylas webhook triggers --category message Webhooks are application-scoped, not grant-scoped: one webhook registered on your application receives notifications for every connected account, identified by the grant_id in each payload. See the notifications overview for the full event model. Before you begin You need a Nylas API key — webhook management is admin-level, so it uses the application's API key rather than a grant. You also need an HTTPS endpoint reachable from the public internet to receive the notifications. The CLI gets the key set up: nylas init # create an account, generate an API key For local de