Webhooks

Cuando tu función recibe webhooks de un servicio externo, cualquiera que conozca la URL puede enviarle datos falsos. La verificación de firma confirma que el evento viene realmente del servicio. ctx.verify* hace esa verificación en una línea: lee la cabecera de firma, resuelve el secret desde tus secrets y lanza un error si no coincide.

Stripe

index.ts

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

export default define({
  name: "stripe-webhook",
  description: "Recibe eventos de Stripe",
  input: z.object({}).passthrough(),
  config: {
    public: true,
    path: "/webhooks/stripe",
    methods: ["POST"],
    mcp: false,
  },
  async handler(event, ctx, request) {
    await ctx.verifyStripe(request);

    ctx.log("Evento verificado", { tipo: event.type });

    if (event.type === "payment_intent.succeeded") {
      await ctx.jelou.send({
        type: "text",
        to: event.data.object.metadata.telefono,
        text: "¡Recibimos tu pago!",
      });
    }

    return { received: true };
  },
});

Configura el secret una sola vez:

jelou functions secrets set stripe-webhook STRIPE_WEBHOOK_SECRET=whsec_...

El event que recibe tu handler ya es el cuerpo validado con Zod. La plataforma consumió el cuerpo del request para validarlo, así que llamar a request.json() dentro del handler lanza un error — usa el primer parámetro.

Proveedores soportados

Verificador	Cabecera	Secret
`ctx.verifyStripe(request)`	`stripe-signature`	`STRIPE_WEBHOOK_SECRET`
`ctx.verifyShopify(request)`	`x-shopify-hmac-sha256`	`SHOPIFY_WEBHOOK_SECRET`
`ctx.verifyMeta(request)`	`x-hub-signature-256`	`META_WEBHOOK_SECRET` o `META_APP_SECRET`
`ctx.verifyHmac(request, opts)`	La que indiques	`opts.secretEnv` o `opts.secret`

Stripe además rechaza eventos con más de 5 minutos de antigüedad, lo que impide que alguien reenvíe un evento antiguo capturado.

Otros servicios

Para Twilio, GitHub, Slack o cualquier servicio con firma HMAC-SHA256, usa ctx.verifyHmac. La cabecera es obligatoria porque no hay un valor por defecto:

await ctx.verifyHmac(request, {
  secretEnv: "WEBHOOK_SECRET",
  header: "x-signature",
});

Rotar secrets

Durante una rotación, acepta el secret viejo y el nuevo a la vez separándolos por coma:

jelou functions secrets set mi-webhook STRIPE_WEBHOOK_SECRET=whsec_nuevo,whsec_viejo

Cuando confirmes que el proveedor ya usa el nuevo, vuelve a dejar uno solo.

Manejar el fallo

Los verificadores lanzan WebhookVerificationError con un código que indica qué pasó:

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

async handler(event, ctx, request) {
  try {
    await ctx.verifyStripe(request);
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      ctx.log("Firma rechazada", { code: err.code, provider: err.provider });
      return new Response(null, { status: 401 });
    }
    throw err;
  }

  return { received: true };
}

Código	Significado
`missing_signature`	El request llegó sin cabecera de firma
`invalid_signature`	La firma no coincide con el cuerpo
`expired_timestamp`	El evento es demasiado antiguo (Stripe)
`missing_secret`	No configuraste el secret de ese proveedor

Si no capturas el error, la función responde con error y el proveedor reintentará el webhook. Para Stripe y Shopify eso suele ser lo correcto solo cuando el fallo es temporal; ante una firma inválida es mejor responder 401 y no reintentar.

Funciones públicas

Los webhooks necesitan config.public: true para que el servicio externo pueda llamarlos sin credenciales de Jelou. Esa es justamente la razón por la que la verificación de firma es obligatoria: es el único control de acceso que queda.

config: {
  public: true,      // el proveedor no tiene API key de Jelou
  methods: ["POST"], // los webhooks siempre son POST
  mcp: false,        // no tiene sentido como herramienta de IA
}

Ver funciones públicas.

Testing

En los tests, createMockContext() deja cada verificador lanzando missing_secret. Para probar el resto del handler, desactiva la verificación:

import { createMockContext, createMockWebhookVerifiers } from "@jelou/functions/testing";

const verifiers = createMockWebhookVerifiers({ stripe: true });

const ctx = createMockContext({
  verifyStripe: verifiers.stripe,
});

// Después de ejecutar el handler puedes revisar las llamadas registradas
verifiers.calls; // [{ method: "stripe", ... }]

Ver la guía de testing.

Funciones públicas

Recibir peticiones sin credenciales de Jelou.

Secrets

Guardar los secrets de cada proveedor.

Ejecuciones diferidas

Agendar un seguimiento al recibir el webhook.

Receptor de webhooks

Ejemplo completo listo para copiar.

Empezando

Desarrollador

Jelou CLI

Mensajería Outbound

Gestión

Marketplace

Canales

Configuración

Facturación

Stripe

Proveedores soportados

Otros servicios

Rotar secrets

Manejar el fallo

Funciones públicas

Testing

Funciones públicas

Secrets

Ejecuciones diferidas

Receptor de webhooks

​Stripe

​Proveedores soportados

​Otros servicios

​Rotar secrets

​Manejar el fallo

​Funciones públicas

​Testing

Funciones públicas

Secrets

Ejecuciones diferidas

Receptor de webhooks

Stripe

Proveedores soportados

Otros servicios

Rotar secrets

Manejar el fallo

Funciones públicas

Testing