usesend-webhooks
/usesend-webhooks
Odbiera i weryfikuje webhooki useSend, czyli open-source'ową platformę e-mail, sprawdzając podpis HMAC i zdarzenia dostarczenia.
- Autor
- hookdeck ↗
- Repozytorium
- webhook-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 21
- Skrypty
- 8
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 16
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 8 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: examples/express/src/index.js, examples/express/test/webhook.test.js, examples/fastapi/main.py, examples/fastapi/test_webhook.py, examples/nextjs/app/webhooks/usesend/route.ts, examples/nextjs/lib/usesend.ts, examples/nextjs/test/webhook.test.ts, examples/nextjs/vitest.config.ts
Co robi i kiedy
Odbiera i weryfikuje webhooki useSend, czyli open-source'ową platformę e-mail, sprawdzając podpis HMAC i zdarzenia dostarczenia.
Oryginalny opis (EN)
Receive and verify useSend webhooks (usesend.com, the open-source email platform formerly called Unsend). Use when setting up a useSend webhook handler, debugging X-UseSend-Signature verification, or handling email events like email.delivered, email.bounced, email.complained, email.opened and email.clicked, plus contact.created and domain.verified. Not Standard Webhooks: the secret is a plain UTF-8 HMAC key and the digest is hex.
Jak działa
- When to Use This Skill
- How Verification Works
- Verification (core)
- Common Event Types
- Environment Variables
- Delivery Behaviour
- Local Development
- Reference Materials
- Recommended: webhook-handler-patterns
- Related Skills
Podgląd SKILL.md
---
name: usesend-webhooks
description: >
Receive and verify useSend webhooks (usesend.com, the open-source email
platform formerly called Unsend). Use when setting up a useSend webhook
handler, debugging X-UseSend-Signature verification, or handling email events
like email.delivered, email.bounced, email.complained, email.opened and
email.clicked, plus contact.created and domain.verified. Not Standard
Webhooks: the secret is a plain UTF-8 HMAC key and the digest is hex.
license: MIT
metadata:
author: hookdeck
version: "0.1.0"
repository: https://github.com/hookdeck/webhook-skills
---
# useSend Webhooks
useSend (usesend.com) is an open-source email sending platform. It sends a
webhook when an email is queued, sent, delivered, bounced or opened, when a
contact changes, and when a domain changes.
## When to Use This Skill
- How do I receive useSend webhooks?
- How do I verify the `X-UseSend-Signature` header?
- Why is my useSend signature verification failing?
- How do I handle `email.delivered`, `email.bounced` or `email.clicked` events?
- How do I set up a webhook in the useSend dashboard?
## How Verification Works
- Headers: `X-UseSend-Signature` (`v1=<hex>`) and `X-UseSend-Timestamp` (Unix
**milliseconds**).
- Signature: lowercase hex HMAC-SHA256, keyed with the secret, over
`{X-UseSend-Timestamp}` + `.` + the **raw request body bytes**.
- The secret is used **whole, as a plain UTF-8 key, including its `whsec_`
prefix**. Nothing is base64-decoded.
- **This is not Standard Webhooks.** There is no `webhook-id` header and the
digest is hex, so do not use the `standardwebhooks` or `svix` libraries.
- A missing or empty header, a malformed value or a mismatch is a `401`.
> **Setup note:** Paste the whole secret, including the whsec_ prefix. useSend uses it as a plain HMAC key.
## Verification (core)
```javascript
const crypto = require('crypto');
// rawBody: Buffer of the exact bytes received (never parsed JSON).
function verifyUseSend(rawBody, signature, timestamp, secret) {
if (!signature || !timestamp || !secret) return false;
const hex = (signature.startsWith('v1=') ? signature.slice(3) : signature).toLowerCase();
if (!/^[0-9a-f]{64}$/.test(hex)) return false; // validate before decoding
const message = Buffer.concat([
Buffer.from(timestamp, 'latin1'), Buffer.from('.'), rawBody,
]);
const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(message).digest();
return crypto.timingSafeEqual(expected, Buffer.from(hex, 'hex'));
}
```
> **For complete handlers with tests**, see [examples/express/](examples/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/).
The examples verify by hand rather than with the `usesend-js` SDK, because the
SDK rejects timestamps older than 5 minutes by default and Hookdeck retries and
replays resend the original timestamp. See
[references/verification.md](references/verification.md).
### Timestamp tolerance is opt-in
The examples do **not** reject old timestamps by default. Hookdeck retries and
replays resend the original headers, and Hookdeck itself applies no tolerance,
so a fixed window would reject legitimate retries. To turn one on, set
`USESEND_WEBHOOK_TOLERANCE_SECONDS` (unset or `0` = off). Remember the header is
in milliseconds. Deduplicate on the payload `id` either way.
## Common Event Types
Dispatch on the body's `type` field.
| Event | Triggered When |
|-------|----------------|
| `email.delivered` | Email was successfully delivered |
| `email.bounced` | Email bounced (permanent or temporary); `data.bounce` has details |
| `email.complained` | Recipient marked the email as spam |
| `email.opened` / `email.clicked` | Recipient opened the email / clicked a link |
| `contact.created` | New contact was created |
| `domain.verified` | Domain verification completed |
| `webhook.test` | Sent by "Send Test" in the dashboard |
useSend documents 20 event types plus the `webhook.test` event (21 in all):
13 `email.*`, 3 `contact.*` and 4 `domain.*`. The examples handle a few and log
the rest. See [references/overview.md](references/overview.md).
## Environment Variables
| Variable | Description |
|----------|-------------|
| `USESEND_WEBHOOK_SECRET` | The webhook signing secret, whole, including `whsec_` |
| `USESEND_WEBHOOK_TOLERANCE_SECONDS` | Optional replay window in seconds (unset or `0` = off) |
## Delivery Behaviour
POST with a JSON body. A `2xx` within 10 seconds acknowledges it. Otherwise
useSend makes 6 attempts in all (immediately, then after about 5, 10, 20, 40 and
80 seconds). A webhook is disabled after 30 consecutive failed calls and is
re-enabled from the dashboard. Duplicates are possible.
## Local Development
For local webhook testing, run the Hookdeck CLI via `npx` — no install required:
```bash
npx hookdeck-cli listen 3000 usesend --path /webhooks/usesend
```
No account required — the CLI creates a guest account on first run and provides a
local tunnel + web UI for inspecting requests.
## Reference Materials
- [references/overview.md](references/overview.md) — What useSend webhooks are, events, payload structure
- [references/setup.md](references/setup.md) — Create the webhook, get the signing secret
- [references/verification.md](references/verification.md) — Signature details and gotchas
- [examples/express/](examples/express/) — Express (Node.js) handler + tests
- [examples/nextjs/](examples/nextjs/) — Next.js App Router handler + tests
- [examples/fastapi/](examples/fastapi/) — FastAPI (Python) handler + tests
## Recommended: webhook-handler-patterns
Install [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)
alongside this skill for cross-cutting concerns. useSend can deliver duplicates:
- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md)
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)
## Related Skills
- [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend email events (Svix-signed)
- [postmark-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/postmark-webhooks) - Postmark delivery, bounce and open webhooks
- [sendgrid-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendgrid-webhooks) - SendGrid event webhooks
- [mailgun-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/mailgun-webhooks) - Mailgun email event webhooks
- [sparkpost-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/sparkpost-webhooks) - SparkPost email event webhooks
- [brevo-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/brevo-webhooks) - Brevo transactional and marketing email events
- [mailjet-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/mailjet-webhooks) - Mailjet event webhooks
- [customerio-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/customerio-webhooks) - Customer.io messaging events
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure
Pliki w paczce (21)
- SKILL.md 8 KB
- examples/express/.env.example 1 KB
- examples/express/README.md 2 KB
- examples/express/package.json 1 KB
- examples/express/src/index.js 4 KB
- examples/express/test/webhook.test.js 7 KB
- examples/fastapi/.env.example 1 KB
- examples/fastapi/README.md 2 KB
- examples/fastapi/main.py 4 KB
- examples/fastapi/requirements.txt 1 KB
- examples/fastapi/test_webhook.py 6 KB
- examples/nextjs/.env.example 1 KB
- examples/nextjs/README.md 2 KB
- examples/nextjs/package.json 1 KB
- examples/nextjs/vitest.config.ts 1 KB
- examples/nextjs/app/webhooks/usesend/route.ts 2 KB
- examples/nextjs/lib/usesend.ts 1 KB
- examples/nextjs/test/webhook.test.ts 7 KB
- references/overview.md 4 KB
- references/setup.md 2 KB
- references/verification.md 4 KB
Wersje
W bazie nie ma innych skilli o nazwie usesend-webhooks.
Migawka bazy z 13.11.2026 · wersja paczki 40e4d70d9eb3 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100jobber-webhooks
Odbiera i weryfikuje webhooki Jobbera, sprawdzając podpis X-Jobber-Hmac-SHA256 i zdarzenia klientów, faktur oraz połączeń aplikacji. - 100mailgun-webhooks
Odbiera i weryfikuje webhooki Mailgun, w tym podpis, oraz obsługuje zdarzenia e-mail: delivered, failed, opened, clicked, unsubscribed i complained.