sendgrid-webhooks
starsforks
How to install sendgrid-webhooks?
hookdeck/webhook-skills/sendgrid-webhooks
$npx -y skills add hookdeck/webhook-skills --skill sendgrid-webhooksReceive and verify SendGrid webhooks. Use when setting up SendGrid webhook handlers, debugging signature verification, or handling email delivery events.
SKILL.md
| 1 | # SendGrid Webhooks |
| 2 | |
| 3 | ## When to Use This Skill |
| 4 | |
| 5 | - Setting up SendGrid webhook handlers for email delivery tracking |
| 6 | - Debugging ECDSA signature verification failures |
| 7 | - Processing email events (bounce, delivered, open, click, spam report) |
| 8 | - Implementing email engagement analytics |
| 9 | |
| 10 | ## Essential Code |
| 11 | |
| 12 | ### Signature Verification (Manual) |
| 13 | |
| 14 | SendGrid uses ECDSA (Elliptic Curve Digital Signature Algorithm) with public key verification. |
| 15 | |
| 16 | ```javascript |
| 17 | // Node.js manual verification |
| 18 | const crypto = require('crypto'); |
| 19 | |
| 20 | function verifySignature(publicKey, payload, signature, timestamp) { |
| 21 | // Decode the base64 signature |
| 22 | const decodedSignature = Buffer.from(signature, 'base64'); |
| 23 | |
| 24 | // Create the signed content |
| 25 | const signedContent = timestamp + payload; |
| 26 | |
| 27 | // Create verifier |
| 28 | const verifier = crypto.createVerify('sha256'); |
| 29 | verifier.update(signedContent); |
| 30 | |
| 31 | // Add PEM headers if not present |
| 32 | let pemKey = publicKey; |
| 33 | if (!pemKey.includes('BEGIN PUBLIC KEY')) { |
| 34 | pemKey = `-----BEGIN PUBLIC KEY-----\n${publicKey}\n-----END PUBLIC KEY-----`; |
| 35 | } |
| 36 | |
| 37 | // Verify the signature |
| 38 | return verifier.verify(pemKey, decodedSignature); |
| 39 | } |
| 40 | |
| 41 | // Express middleware |
| 42 | app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => { |
| 43 | const signature = req.get('X-Twilio-Email-Event-Webhook-Signature'); |
| 44 | const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp'); |
| 45 | |
| 46 | if (!signature || !timestamp) { |
| 47 | return res.status(400).send('Missing signature headers'); |
| 48 | } |
| 49 | |
| 50 | const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY; |
| 51 | const payload = req.body.toString(); |
| 52 | |
| 53 | if (!verifySignature(publicKey, payload, signature, timestamp)) { |
| 54 | return res.status(400).send('Invalid signature'); |
| 55 | } |
| 56 | |
| 57 | // Process events |
| 58 | const events = JSON.parse(payload); |
| 59 | console.log(`Received ${events.length} events`); |
| 60 | |
| 61 | res.sendStatus(200); |
| 62 | }); |
| 63 | ``` |
| 64 | |
| 65 | ### Using SendGrid SDK |
| 66 | |
| 67 | ```javascript |
| 68 | const { EventWebhook } = require('@sendgrid/eventwebhook'); |
| 69 | |
| 70 | const verifyWebhook = new EventWebhook(); |
| 71 | const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY; |
| 72 | |
| 73 | app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => { |
| 74 | const signature = req.get('X-Twilio-Email-Event-Webhook-Signature'); |
| 75 | const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp'); |
| 76 | |
| 77 | const isValid = verifyWebhook.verifySignature( |
| 78 | publicKey, |
| 79 | req.body, |
| 80 | signature, |
| 81 | timestamp |
| 82 | ); |
| 83 | |
| 84 | if (!isValid) { |
| 85 | return res.status(400).send('Invalid signature'); |
| 86 | } |
| 87 | |
| 88 | // Process webhook |
| 89 | res.sendStatus(200); |
| 90 | }); |
| 91 | ``` |
| 92 | |
| 93 | ## Common Event Types |
| 94 | |
| 95 | | Event | Description | Use Cases | |
| 96 | |-------|-------------|-----------| |
| 97 | | `processed` | Message has been received and is ready to be delivered | Track email processing | |
| 98 | | `delivered` | Message successfully delivered to recipient | Delivery confirmation | |
| 99 | | `bounce` | Message permanently rejected (includes type='blocked' for blocked messages) | Update contact lists, handle failures | |
| 100 | | `deferred` | Temporary delivery failure | Monitor delays | |
| 101 | | `open` | Recipient opened the email | Engagement tracking | |
| 102 | | `click` | Recipient clicked a link | Link tracking, CTR analysis | |
| 103 | | `spam report` | Email marked as spam | List hygiene, sender reputation | |
| 104 | | `unsubscribe` | Recipient unsubscribed | Update subscription status | |
| 105 | | `group unsubscribe` | Recipient unsubscribed from a group | Update group subscription preferences | |
| 106 | | `group resubscribe` | Recipient resubscribed to a group | Update group subscription preferences | |
| 107 | |
| 108 | ## Environment Variables |
| 109 | |
| 110 | ```bash |
| 111 | # Your SendGrid webhook verification key (public key) |
| 112 | SENDGRID_WEBHOOK_VERIFICATION_KEY="MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..." |
| 113 | ``` |
| 114 | |
| 115 | ## Local Development |
| 116 | |
| 117 | For local webhook testing, use Hookdeck CLI: |
| 118 | |
| 119 | ```bash |
| 120 | npx hookdeck-cli listen 3000 sendgrid --path /webhooks/sendgrid |
| 121 | ``` |
| 122 | |
| 123 | No account required. Provides local tunnel + web UI for inspecting requests. |
| 124 | |
| 125 | ## Resources |
| 126 | |
| 127 | - [overview.md](references/overview.md) - What SendGrid webhooks are, common event types |
| 128 | - [setup.md](references/setup.md) - Configure webhooks in SendGrid dashboard, get verification key |
| 129 | - [verification.md](references/verification.md) - ECDSA signature verification details and gotchas |
| 130 | - [examples/](examples/) - Complete implementations for Express, Next.js, and FastAPI |
| 131 | |
| 132 | ## Related Skills |
| 133 | |
| 134 | - `webhook-handler-patterns` - Cross-cutting patterns (idempotency, retries, framework guides) |
| 135 | - [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 |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
