npx skills add ...
npx skills add encoredev/skills --skill encore-go-webhook
npx skills add encoredev/skills --skill encore-go-webhook
Receive inbound webhooks from external services (Stripe, GitHub, Slack, Twilio, etc.) in Encore Go using `//encore:api raw`. The right skill any time the user names a third-party provider that POSTs events to a URL you own.
Use //encore:api raw to receive inbound webhooks from third-party services. Raw endpoints give you direct access to http.ResponseWriter and *http.Request, which you need for signature verification (the verification typically requires the unparsed raw body).
//encore:api rawMost providers sign webhooks. Read the secret with secrets (see the encore-go-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.webhook.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-go-pubsub) instead of doing it in the request handler.
//encore:api raw only for webhooks and other low-level HTTP integrations.secrets struct{...}; never inline it.//encore:api from the encore-go-api skill.package webhooks
import (
"github.com/stripe/stripe-go/v76/webhook"
)
var secrets struct {
StripeWebhookSecret string
}
//encore:api public raw path=/webhooks/stripe method=POST
func StripeWebhook(w http.ResponseWriter, req *http.Request) {
body, _ := io.ReadAll(req.Body)
sig := req.Header.Get("Stripe-Signature")
event, err := webhook.ConstructEvent(body, sig, secrets.StripeWebhookSecret)
if err != nil {
http.Error(w, "signature verification failed", http.StatusBadRequest)
return
}
// event is now trusted — handle it.
_ = event
w.WriteHeader(http.StatusOK)
}package webhooks
import (
"encore.dev/pubsub"
"net/http"
)
type StripeEvent struct {
ID string `json:"id"`
Type string `json:"type"`
Data any `json:"data"`
}
var StripeEvents = pubsub.NewTopic[*StripeEvent]("stripe-events", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
//encore:api public raw path=/webhooks/stripe method=POST
func StripeWebhook(w http.ResponseWriter, req *http.Request) {
// ... verify signature, parse event ...
_, _ = StripeEvents.Publish(req.Context(), &StripeEvent{
ID: event.ID, Type: string(event.Type), Data: event.Data,
})
w.WriteHeader(http.StatusOK)
}