npx skills add ...
npx skills add encoredev/skills --skill encore-webhook
npx skills add encoredev/skills --skill encore-webhook
Receive inbound webhooks from external services (Stripe, GitHub, Slack, Twilio, etc.) using `api.raw(...)` from `encore.dev/api`. The right skill any time the user names a third-party provider that POSTs events to a URL you own.
Use api.raw(...) to receive inbound webhooks from third-party services. Raw endpoints give you direct access to the Node.js-style request and response objects, which you need for signature verification (the verification typically requires the unparsed raw body).
api.rawMost providers sign webhooks. Read the secret with secret(...) from encore.dev/config (see the encore-secret skill) and verify before trusting the payload:
For GitHub, verify the HMAC-SHA256 in the X-Hub-Signature-256 header against the raw body using your webhook secret.
| Provider | Signature header | Verification |
|---|---|---|
| Stripe | Stripe-Signature | stripe.webhooks.constructEvent(rawBody, sig, secret) |
| GitHub | X-Hub-Signature-256 | HMAC-SHA256 over the raw body |
| Slack | X-Slack-Signature | HMAC-SHA256 over v0:{timestamp}:{rawBody} |
| Shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 (base64) over the raw body |
| Twilio | X-Twilio-Signature | HMAC-SHA1 over URL + sorted form fields |
Webhook senders retry on non-2xx or slow responses. Acknowledge with a 2xx as soon as the payload is verified, then enqueue the actual work via Pub/Sub (see encore-pubsub) instead of doing it in the request handler.
api.raw only for webhooks and other low-level HTTP integrations.secret(...); never inline it.api(...) from the encore-api skill.import { secret } from "encore.dev/config";
const stripeWebhookSecret = secret("StripeWebhookSecret");
// inside handler:
import Stripe from "stripe";
const stripe = new Stripe(stripeApiKey());
const event = stripe.webhooks.constructEvent(rawBody, sig, stripeWebhookSecret());import { Topic } from "encore.dev/pubsub";
interface StripeEvent { id: string; type: string; data: unknown; }
const stripeEvents = new Topic<StripeEvent>("stripe-events", {
deliveryGuarantee: "at-least-once",
});
// inside the raw handler, after verification:
await stripeEvents.publish({ id: event.id, type: event.type, data: event.data });
res.writeHead(200); res.end();