Receptor de webhook

Você recebe callbacks POST de qualquer serviço externo (gateways de pagamento, GitHub, CRMs, etc.), valida o payload e processa o evento. Padrão: rota personalizada + somente POST + MCP desativado + validação de payload.

index.ts

import { define, z } from "@jelou/functions";

export default define({
  name: "webhook-receiver",
  description: "Receives and processes webhooks from external services",
  input: z.object({
    event: z.string(),
    data: z.object({
      id: z.string(),
      status: z.string(),
      metadata: z.record(z.unknown()).optional(),
    }),
  }),
  config: {
    path: "/webhooks/events",
    methods: ["POST"],
    mcp: false,
  },
  handler: async (input, ctx) => {
    ctx.log("Webhook received", {
      event: input.event,
      id: input.data.id,
      requestId: ctx.requestId,
    });

    const secret = ctx.env.get("WEBHOOK_SECRET");

    switch (input.event) {
      case "payment.completed": {
        ctx.log("Payment completed", { id: input.data.id });
        return { acknowledged: true, action: "payment_processed" };
      }
      case "user.created": {
        ctx.log("User created", { id: input.data.id });
        return { acknowledged: true, action: "user_synced" };
      }
      default: {
        ctx.log("Unhandled event", { event: input.event });
        return { acknowledged: true, action: "ignored" };
      }
    }
  },
});

Testes locais

curl -X POST http://localhost:3000/webhooks/events \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "data": {"id": "pay_123", "status": "success"}}'

Por que funciona dessa forma

config.methods: ["POST"] — rejeita GET, PUT, etc. Webhooks são sempre POST.
config.mcp: false — não faz sentido expor um webhook como ferramenta de IA.
config.path — rota fixa que você configura no serviço externo.
O schema input valida a estrutura do payload antes de chegar ao handler.

Verificar a assinatura do webhook

Uma função pública pode ser chamada por qualquer pessoa que conheça a URL. Em produção, verifique a assinatura do serviço antes de processar o evento — ctx.verify* faz isso em uma linha:

handler: async (input, ctx, request) => {
  await ctx.verifyHmac(request, {
    secretEnv: "WEBHOOK_SECRET",
    header: "x-webhook-signature",
  });

  // Processar o evento...
  return { acknowledged: true };
}

Se a assinatura não corresponder, lança erro e o evento não chega à sua lógica. Para Stripe, Shopify e Meta use o verificador de cada provedor, que já conhece seu header e seu secret:

await ctx.verifyStripe(request);
await ctx.verifyShopify(request);
await ctx.verifyMeta(request);

Configure o secret antes do deploy: jelou functions secrets set meu-webhook WEBHOOK_SECRET=whsec_...

Guia de webhooks

Provedores suportados, rotação de secrets, códigos de erro e testes.

⌘I

Primeiros Passos

Desenvolvedor

Jelou CLI

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

Testes locais

Por que funciona dessa forma

Verificar a assinatura do webhook

Guia de webhooks

​Testes locais

​Por que funciona dessa forma

​Verificar a assinatura do webhook

Guia de webhooks

Testes locais

Por que funciona dessa forma

Verificar a assinatura do webhook