Skip to main content
skill CX Codex

sendgrid-webhooks — Claude Code skill for SendGrid webhooks

sendgrid-webhooks is a Claude Code skill that sets up SendGrid webhook handlers, validates signatures, and processes email events for delivery tracking and verification debugging.

MIT 253 installs ★ 103 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks -a claude-code
Open on GitHub

What sendgrid-webhooks does

This skill covers receiving SendGrid webhooks and validating ECDSA signatures with a public key. Its Node.js examples show both a manual check using crypto and verification with @sendgrid/eventwebhook. The handler reads the request body unchanged, checks the signature headers, then parses the event payload.

Events include delivery, bounce, deferral, opens, clicks, spam reports, and unsubscribes. Set SENDGRID_WEBHOOK_VERIFICATION_KEY to the verification public key. For local testing, the skill uses npx hookdeck-cli listen 3000 sendgrid --path /webhooks/sendgrid, with a local tunnel and request inspection UI. Keep the raw request body intact until signature validation; parsing it first can break the check.

What it helps with

  • validate a SendGrid webhook signature
  • handle email delivery and bounce events
  • track opens and link clicks
  • update subscription status after an unsubscribe
  • test a webhook locally with Hookdeck CLI

Example prompts for the agent

  • Set up an Express handler for SendGrid webhooks and validate its signature.
  • Process delivery, bounce, and open events from a SendGrid webhook.
  • Show me how to test a SendGrid webhook locally with Hookdeck CLI.

How to install sendgrid-webhooks

1Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/sendgrid-webhooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sendgrid-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sendgrid-webhooks

How do I install sendgrid-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks -a claude-code. The skill file is installed at ~/.claude/skills/sendgrid-webhooks/SKILL.md.

What does sendgrid-webhooks do?

It guides you through building SendGrid webhook handlers, checking ECDSA signatures, and processing email delivery and engagement events.

What do I need to verify a webhook signature?

Provide the SendGrid public verification key through SENDGRID_WEBHOOK_VERIFICATION_KEY. The Node.js examples use either crypto or @sendgrid/eventwebhook.

Source text

SKILL.md · MIT
---
name: sendgrid-webhooks
description: >
  Receive and verify SendGrid webhooks. Use when setting up SendGrid webhook
  handlers, debugging signature verification, or handling email delivery events.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# SendGrid Webhooks

## When to Use This Skill

- Setting up SendGrid webhook handlers for email delivery tracking
- Debugging ECDSA signature verification failures
- Processing email events (bounce, delivered, open, click, spam report)
- Implementing email engagement analytics

## Essential Code

### Signature Verification (Manual)

SendGrid uses ECDSA (Elliptic Curve Digital Signature Algorithm) with public key verification.

```javascript
// Node.js manual verification
const crypto = require('crypto');

function verifySignature(publicKey, payload, signature, timestamp) {
  // Decode the base64 signature
  const decodedSignature = Buffer.from(signature, 'base64');

  // Create the signed content
  const signedContent = timestamp + payload;

  // Create verifier
  const verifier = crypto.createVerify('sha256');
  verifier.update(signedContent);

  // Add PEM headers if not present
  let pemKey = publicKey;
  if (!pemKey.includes('BEGIN PUBLIC KEY')) {
    pemKey = `-----BEGIN PUBLIC KEY-----\n${publicKey}\n-----END PUBLIC KEY-----`;
  }

  // Verify the signature
  return verifier.verify(pemKey, decodedSignature);
}

// Express middleware
app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');
  const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp');

  if (!signature || !timestamp) {
    return res.status(400).send('Missing signature headers');
  }

  const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY;
  const payload = req.body.toString();

  if (!verifySignature(publicKey, payload, signature, timestamp)) {
    return res.status(400).send('Invalid signature');
  }

  // Process events
  const events = JSON.parse(payload);
  console.log(`Received ${events.length} events`);

  res.sendStatus(200);
});
```

### Using SendGrid SDK

```javascript
const { EventWebhook } = require('@sendgrid/eventwebhook');

const verifyWebhook = new EventWebhook();
const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY;

app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');
  const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp');

  const isValid = verifyWebhook.verifySignature(
    publicKey,
    req.body,
    signature,
    timestamp
  );

  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }

  // Process webhook
  res.sendStatus(200);
});
```

## Common Event Types

| Event | Description | Use Cases |
|-------|-------------|-----------|
| `processed` | Message has been received and is ready to be delivered | Track email processing |
| `delivered` | Message successfully delivered to recipient | Delivery confirmation |
| `bounce` | Message permanently rejected (includes type='blocked' for blocked messages) | Update contact lists, handle failures |
| `deferred` | Temporary delivery failure | Monitor delays |
| `open` | Recipient opened the email | Engagement tracking |
| `click` | Recipient clicked a link | Link tracking, CTR analysis |
| `spam report` | Email marked as spam | List hygiene, sender reputation |
| `unsubscribe` | Recipient unsubscribed | Update subscription status |
| `group unsubscribe` | Recipient unsubscribed from a group | Update group subscription preferences |
| `group resubscribe` | Recipient resubscribed to a group | Update group subscription preferences |

## Environment Variables

```bash
# Your SendGrid webhook verification key (public key)
SENDGRID_WEBHOOK_VERIFICATION_KEY="MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
```

## Local Development

For local webhook testing, use Hookdeck CLI:

```bash
npx hookdeck-cli listen 3000 sendgrid --path /webhooks/sendgrid
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Resources

- [overview.md](references/overview.md) - What SendGrid webhooks are, common event types
- [setup.md](references/setup.md) - Configure webhooks in SendGrid dashboard, get verification key
- [verification.md](references/verification.md) - ECDSA signature verification details and gotchas
- [examples/](examples/) - Complete implementations for Express, Next.js, and FastAPI

## Related Skills

- `webhook-handler-patterns` - Cross-cutting patterns (idempotency, retries, framework guides)
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

© hookdeck · MIT · hookdeck/webhook-skills

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
webhook-handler-patterns webhook-handler-patterns — a skill for Claude Code guides webhook handler architecture: signature verification, parsing, and idempotency. Triggers when writing webhook endpoints in Express, Next.js, or FastAPI. CX Codex +1 456installs shopify-webhooks Receives and verifies Shopify webhooks: HMAC-SHA256 signature in base64, order, product, and customer events. Requires app API secret. CX Codex +1 291installs resend-webhooks resend-webhooks sets up Resend webhook handlers, Svix signature checks, and email event processing for Express or FastAPI projects. CX Codex +1 266installs paddle-webhooks paddle-webhooks helps your coding agent verify HMAC-SHA256 signatures and process Paddle billing webhooks properly. CX Codex +1 258installs elevenlabs-webhooks Teaches your coding assistant how to verify and handle ElevenLabs webhooks. Useful when implementing call transcript handlers or debugging signature validation. CX Codex +1 237installs hookdeck-event-gateway Connects Hookdeck Event Gateway — webhook infrastructure with queue, retries and monitoring. CX Codex +1 214installs woocommerce-webhooks Sets up and validates WooCommerce webhooks in Node.js and Python. Handles signature verification and store events like order or product updates. CX Codex +1 213installs clerk-webhooks This skill guides you through receiving Clerk webhooks and checking their signatures. Use it when building handlers for user, session, or organization events. CX Codex +1 210installs

Project sponsors

Companies that keep this analytics open