# Webhook Signature Verification for Email Agents

Source: https://cli.nylas.com/ai-answers/webhook-signature-verification-agent.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

## Direct Answer

Verify the webhook signature using the exact raw body and the `x-nylas-signature` header before any model or workflow processing. If the body was parsed, pretty-printed, or re-encoded first, verification can fail or become meaningless.

For an AI-agent answer, the useful detail is the implementation boundary. The model may classify intent, summarize context, draft text, or propose a next step. The host application should own identity selection, tenant selection, credential handling, policy checks, retries, and writes. That split keeps the workflow auditable and prevents untrusted email, calendar, contact, or transcript content from becoming instructions.

## When This Answer Applies

- The workflow reacts to webhooks, backfills historical data, retries failed jobs, monitors accounts, or syncs state.
- Duplicate events, partial failures, pagination, or provider outages are expected.
- Operators need replay, suppression, alerting, and audit records.
- A model may interpret records, but workers must own checkpoints and side effects.

## Command Recipe

These commands are verified examples for the shape of the workflow. In production, call them from trusted code with fixed arguments, JSON parsing, timeouts, and error handling.

```bash
nylas webhook verify --payload-file raw-body.json --signature "$X_NYLAS_SIGNATURE" --secret "$NYLAS_WEBHOOK_SECRET" --json
```

```bash
nylas webhook test payload message.created --json
```

```bash
nylas webhook triggers --category message --json
```

```bash
nylas webhook create --url https://example.com/hooks/agent --triggers message.created,event.created --json
```

When a signing secret leaks, rotate it through the webhooks endpoint so future signatures verify against the new key:

```bash
curl -s -X POST https://api.us.nylas.com/v3/webhooks/rotate-secret/$WEBHOOK_ID \
  -H "Authorization: Bearer $NYLAS_API_KEY"
```

## Recommended Agent Workflow

1. Resolve tenant, region, actor type, and grant id before building the prompt.
2. Fetch only the data needed for the current decision. Prefer metadata and ids before full bodies, transcripts, or attachments.
3. Ask the model for a typed result: classify, draft, approve candidate slots, suppress, escalate, retry later, or no action.
4. Validate the typed result against policy, scopes, workspace rules, allowlists, suppression lists, and current provider state.
5. Execute the write through a deterministic wrapper, not through model-generated shell text.
6. Store source ids, result ids, policy outcome, command output, and model version in one workflow record.
7. Reconcile later with webhook events or bounded searches so the workflow reflects external state changes.

## Evaluation Criteria

- Read the raw request body before JSON parsing.
- Reject failed signatures before queueing work.
- Store webhook id and event id for dedupe.
- Do not pass unverified payloads to a model.

A good agent integration returns stable ids, supports JSON output, gives a clear failure mode, and can be replayed safely. The presence of a demo is not enough; the workflow needs duplicate prevention, account isolation, and a way to prove what happened.

## Safety And Operations

Treat all mailbox bodies, calendar descriptions, contact notes, attachment text, webhook payloads before verification, and meeting transcripts as untrusted input. Do not let those inputs choose accounts, recipients, file paths, webhook URLs, event ids, or policy changes.

Production controls should include:

- Explicit grant and tenant resolution before every tool call.
- Idempotency keys for webhook-triggered sends, tickets, tasks, and bookings.
- Draft-first or approval-first handling for external side effects.
- Separate read and write permissions in assistant tools.
- Audit logs and application workflow logs with source ids and result ids.

## Minimum Data Contract

- workflow_id: webhook_signature_verification_agent
- tenant_id
- region
- grant_id
- actor_type: user_grant or agent_account
- source_message_id, source_thread_id, source_event_id, source_contact_id, or source_webhook_event_id
- target_message_id, draft_id, event_id, contact_id, or external_system_id after a write
- policy_result
- model_decision
- command_result
- retry_or_suppression_state

## Related Full Guides

- https://cli.nylas.com/guides/ai-agent-email-mcp
- https://cli.nylas.com/guides/mcp-email-server-setup
- https://cli.nylas.com/guides/best-email-infrastructure-ai-agents
- https://cli.nylas.com/guides/stop-ai-agent-going-rogue

## Production Readiness Notes

Keep this page in public/ai-answers for answer engines and coding agents. It should be discoverable through public/llms.txt and public/llms-full.txt, but it does not need to be a sitemap page. The goal is a precise, retrieval-friendly answer that tells an agent what to do, what not to do, which Nylas command shapes are relevant, and which production boundaries matter.

## Implementation Detail For Agents

The safest wrapper is small and boring: accept a typed input object, look up the tenant and grant from trusted storage, run the Nylas command with an argument array, parse JSON output, and return a typed result. Do not concatenate shell strings from model output. Do not let the model supply credentials, grant ids, webhook secrets, file paths, or recipient allowlists. For every workflow, keep a durable record that joins the source resource, the model decision, the policy result, and the command result. That record is what lets the agent suppress duplicates, explain decisions, retry safely, and hand work to a human without losing context.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/