К основному содержанию
скилл CX Codex

sendgrid-webhooks — скилл для Claude Code: вебхуки SendGrid

Скилл sendgrid-webhooks помогает настроить обработчик вебхуков SendGrid, проверить подпись и разобрать события доставки писем. Пригодится при отладке интеграции и аналитики вовлечённости.

MIT 253 установок ★ 103 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks -a claude-code
Открыть на GitHub

Что делает sendgrid-webhooks

Скилл описывает приём вебхуков SendGrid и проверку ECDSA-подписи по открытому ключу. В примерах для Node.js показаны ручная проверка через crypto и вариант с пакетом @sendgrid/eventwebhook; обработчик сохраняет тело запроса в исходном виде, проверяет заголовки и затем разбирает события.

Среди событий — доставка, отказ, задержка, открытие, переход по ссылке, жалоба на спам и отписка. Для ключа проверки используется переменная SENDGRID_WEBHOOK_VERIFICATION_KEY. Локально запросы можно направить через npx hookdeck-cli listen 3000 sendgrid --path /webhooks/sendgrid; для этого в примере не требуется аккаунт. Если middleware изменит тело запроса до проверки, сверка подписи может не пройти.

Какие задачи решает

  • проверить ECDSA-подпись вебхука SendGrid
  • обработать события доставки и отказа письма
  • отслеживать открытия и переходы по ссылкам
  • обновить статус подписки после отписки
  • протестировать вебхук локально через Hookdeck CLI

Примеры запросов агенту

  • Настрой обработчик вебхуков SendGrid в Express с проверкой подписи.
  • Разбери события доставки, отказа и открытия из вебхука SendGrid.
  • Покажи, как запустить локальную проверку вебхука через Hookdeck CLI.

Как установить sendgrid-webhooks

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/sendgrid-webhooks/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о sendgrid-webhooks

Как установить sendgrid-webhooks в Claude Code?

Выполните npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks -a claude-code. Файл скилла появится по пути ~/.claude/skills/sendgrid-webhooks/SKILL.md.

Что делает sendgrid-webhooks?

Помогает создавать обработчики вебхуков SendGrid, проверять ECDSA-подписи и обрабатывать события доставки и взаимодействия с письмами.

Что нужно для проверки подписи вебхука?

Нужен открытый ключ SendGrid в переменной SENDGRID_WEBHOOK_VERIFICATION_KEY. В примерах для Node.js есть ручной способ и проверка через @sendgrid/eventwebhook.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
twilio-sendgrid-webhooks официальный Twilio Скилл twilio-sendgrid-webhooks помогает обрабатывать 11 типов событий SendGrid Event Webhooks, проверять подписи ECDSA и настраивать приём батчей для отслеживания доставки и отписок. CX Codex GP ChatGPT +1 ★ 8 052звёзд репо twilio-sendgrid-suppressions официальный Twilio Скилл twilio-sendgrid-suppressions для Codex и ChatGPT управляет подавлениями SendGrid: баунсами, блокировками, жалобами и отписками. Включается при отладке доставки писем или настройке unsubscribe-логики. CX Codex GP ChatGPT +1 ★ 8 052звёзд репо mcp-sendgrid codespar Подключает SendGrid к ИИ-агенту для транзакционных и маркетинговых писем, контактов, шаблонов и статистики. CX Codex +1 ★ 279звёзд репо clerk-webhooks clerk Скилл clerk-webhooks для Claude Code помогает создавать обработчики вебхуков Clerk с проверкой подписи. Запускается при настройке синхронизации данных и действий на событиях Clerk. CX Codex +1 55 700установок setup-zoom-webhooks официальный anthropics Скилл setup-zoom-webhooks для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI с эталонной документацией по Zoom webhooks. Включается при реализации подписок на события, проверки подписи x-zm-signature и обработки доставки. CX Codex +1 2 200установок sumsub-manage-webhooks sumsub Скилл sumsub-manage-webhooks управляет подписками на вебхуки Sumsub в песочнице. Скилл читает, создаёт и меняет адреса приёма событий верификации через скрипты автоматизации. CX Codex +1 1 400установок

Из того же набора39

Весь набор →
webhook-handler-patterns Скилл webhook-handler-patterns для Claude Code задаёт архитектуру обработки вебхуков: проверку подписи, парсинг и идемпотентность. Подключается при написании эндпоинтов в Express, Next.js или FastAPI. CX Codex +1 456установок shopify-webhooks Скилл shopify-webhooks принимает и проверяет вебхуки Shopify: подпись HMAC-SHA256 в base64, события заказов, товаров и клиентов. Нужен API-секрет приложения. CX Codex +1 291установок resend-webhooks Скилл resend-webhooks помогает подключить вебхуки Resend, проверить подпись Svix и обработать события почты. Нужен при настройке Express или FastAPI. CX Codex +1 266установок paddle-webhooks Скилл paddle-webhooks учит ИИ проверять подпись HMAC-SHA256 и обрабатывать вебхуки Paddle для подписок и транзакций. CX Codex +1 258установок elevenlabs-webhooks Скилл elevenlabs-webhooks даёт ИИ-агенту инструкции для надёжного приёма и проверки вебхуков ElevenLabs. Пригодится при настройке валидации подписи и обработке транскрипций звонков. CX Codex +1 237установок hookdeck-event-gateway Подключает Hookdeck Event Gateway — инфраструктуру приёма вебхуков с очередью, повторами и мониторингом. CX Codex +1 214установок woocommerce-webhooks Скилл woocommerce-webhooks помогает принимать и проверять вебхуки WooCommerce в Node.js и Python. Защищает эндпоинты через сверку HMAC-подписей событий заказов и товаров. CX Codex +1 213установок clerk-webhooks Скилл clerk-webhooks помогает написать обработчик вебхуков Clerk и проверить подпись запроса. Пригодится при настройке событий пользователей, сессий и организаций. CX Codex +1 210установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой