ericrisco/rsc-harness / skills/webhooks
webhooks
VerifiedUse when building the receiving end of a webhook — a provider-agnostic endpoint that proves pushed events are authentic and never processes one twice: raw-body HMAC, ~5-min replay window, idempotency on the event id, fast-ack-then-queue. NOT the Stripe-Signature scheme (that is stripe), NOT outbound clients you call (that is api-connector-builder).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.0 KB |
| evals/README.md | markdown | 1.0 KB |
| evals/cases.yaml | config | 4.1 KB |
| references/framework-raw-body.md | markdown | 3.5 KB |
| references/signature-schemes.md | markdown | 3.5 KB |
| scripts/verify.shexecutable | script | 6.3 KB |
references/signature-schemes.md
View on GitHub# Per-provider signature schemes
Every webhook signature is the same primitive — `HMAC-SHA256(secret, message)`
compared in constant time — wrapped in a different header layout. Map the
provider onto the generic verify routine in `SKILL.md` by answering three
questions: **which headers carry the id/timestamp/signature**, **what string is
signed**, and **how is the signature encoded**.
## Comparison table
| Provider | Signature header | Signed message | Encoding | Timestamp source |
|----------|------------------|----------------|----------|------------------|
| Standard Webhooks | `webhook-signature` (`v1,<sig> …` space-separated) | `{webhook-id}.{webhook-timestamp}.{raw-body}` | base64 | `webhook-timestamp` header (Unix seconds) |
| Stripe | `Stripe-Signature` (`t=<ts>,v1=<sig>`) | `{t}.{raw-body}` | hex | `t` field inside the header |
| GitHub | `X-Hub-Signature-256` (`sha256=<sig>`) | raw body only | hex | none — rely on TLS + secret; no replay window |
| Shopify | `X-Shopify-Hmac-SHA256` | raw body only | base64 | none |
| Slack | `X-Slack-Signature` (`v0=<sig>`) + `X-Slack-Request-Timestamp` | `v0:{timestamp}:{raw-body}` | hex | `X-Slack-Request-Timestamp` header |
| Svix | same as Standard Webhooks (`svix-id/timestamp/signature` or `webhook-*`) | `{id}.{timestamp}.{raw-body}` | base64 | timestamp header |
Notes that bite:
- **Stripe and Standard Webhooks both prefix versions and both allow multiple
comma/space-separated signatures** for secret rotation — accept the request if
*any* candidate matches. Never `break` on the first mismatch.
- **GitHub and Shopify sign the body alone** (no id/timestamp), so they have no
built-in replay window. Lean on HTTPS and the secret; if you need replay
protection, dedupe on a delivery id (`X-GitHub-Delivery`).
- **Slack signs `v0:{ts}:{body}`** with a colon separator and a literal `v0:`
prefix — different layout from the dot-joined Standard Webhooks string.
- For the **Stripe** scheme specifically (event model, `stripe listen`, the
billing flows) use `../../stripe/SKILL.md`; this table only covers verifying
the signature.
## Verify primitives by language
The two things that must be language-correct: feed the **raw bytes** to the HMAC,
and use the **constant-time** comparator.
| Language | HMAC-SHA256 | Constant-time compare |
|----------|-------------|------------------------|
| Node.js | `crypto.createHmac("sha256", key).update(raw).digest()` | `crypto.timingSafeEqual(a, b)` (equal-length Buffers) |
| Python | `hmac.new(key, raw, hashlib.sha256).digest()` | `hmac.compare_digest(a, b)` |
| Go | `hmac.New(sha256.New, key); mac.Write(raw)` | `hmac.Equal(expected, got)` |
| Ruby | `OpenSSL::HMAC.digest("SHA256", key, raw)` | `Rack::Utils.secure_compare(a, b)` |
| PHP | `hash_hmac("sha256", $raw, $key, true)` | `hash_equals($a, $b)` |
```go
// Go — Standard Webhooks verify, constant time, raw body in.
func verify(raw []byte, id, ts, header, secretB64 string) bool {
key, _ := base64.StdEncoding.DecodeString(secretB64)
mac := hmac.New(sha256.New, key)
mac.Write([]byte(id + "." + ts + "."))
mac.Write(raw)
expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
for _, part := range strings.Fields(header) { // space-separated for rotation
sig := strings.TrimPrefix(part, "v1,")
if hmac.Equal([]byte(sig), []byte(expected)) {
return true
}
}
return false
}
```
Whatever the layout, the order from `SKILL.md` does not change: raw body →
verify → timestamp window → dedupe → enqueue → `2xx`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |