Setting the chapter. One moment.
Skills
Chapter 28 of 28
Receive inbound webhooks from external services (Stripe, GitHub, Slack, Twilio, etc.) using api.raw(...) from encore.dev/api.
1 minute · 213 words · 8 sections
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).
import { api } from "encore.dev/api";api.rawexport const stripeWebhook = api.raw(
{ expose: true, path: "/webhooks/stripe", method: "POST" },
async (req, res) => {
const sig = req.headers["stripe-signature"];
// Read raw body
const chunks: Buffer[] = [];
for await (const chunk of req) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString("utf8");
// Verify signature, parse event...
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ received: true }));
}
);Most providers sign webhooks. Read the secret with secret(...) from encore.dev/config (see the encore-secret skill) and verify before trusting the payload:
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());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.
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();api.raw only for webhooks and other low-level HTTP integrations.secret(...); never inline it.api(...) from the encore-api skill.Install this repository
npx skills add encoredev/skills/plugin marketplace add encoredev/skillsSkills install per repository, not per chapter — the CLI has no documented per-skill form, so we do not print one.
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.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
main, last pushed 15 May 2026.SKILL.md, not by matching a directory convention. One layout observed: encore/*/SKILL.md.h1 and no skipped levels:.claude-plugin/marketplace.json by Encore, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree./encoredev/skills.md, and each chapter at its own .md URL.