hookdeck/webhook-skills/sendgrid-webhooks

Claude Code and agent skill by hookdeck/webhook-skills

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Receive and verify SendGrid webhooks. Use when setting up SendGrid webhook handlers, debugging signature verification, or handling email delivery events.

Install

npx vskill@latest install hookdeck/webhook-skills/sendgrid-webhooks

SKILL.md

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

EventDescriptionUse Cases
processedMessage has been received and is ready to be deliveredTrack email processing
deliveredMessage successfully delivered to recipientDelivery confirmation
bounceMessage permanently rejected (includes type='blocked' for blocked messages)Update contact lists, handle failures
deferredTemporary delivery failureMonitor delays
openRecipient opened the emailEngagement tracking
clickRecipient clicked a linkLink tracking, CTR analysis
spam reportEmail marked as spamList hygiene, sender reputation
unsubscribeRecipient unsubscribedUpdate subscription status
group unsubscribeRecipient unsubscribed from a groupUpdate group subscription preferences
group resubscribeRecipient resubscribed to a groupUpdate 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 - What SendGrid webhooks are, common event types
  • setup.md - Configure webhooks in SendGrid dashboard, get verification key
  • verification.md - ECDSA signature verification details and gotchas
  • examples/ - Complete implementations for Express, Next.js, and FastAPI

Related Skills

  • webhook-handler-patterns - Cross-cutting patterns (idempotency, retries, framework guides)
  • hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
69
Repository forks
7
7-day trend score
21

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 6 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/hookdeck/webhook-skills/sendgrid-webhooks/badge)](https://verified-skill.com/skills/hookdeck/webhook-skills/sendgrid-webhooks)

Something wrong with this skill or its page? Tell us.