Webhooks

When your function receives webhooks from an external service, anyone who knows the URL can send it fake data. Signature verification confirms the event really came from the service. ctx.verify* does that check in one line: it reads the signature header, resolves the secret from your secrets, and throws if it does not match.

Stripe

index.ts

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

export default define({
  name: "stripe-webhook",
  description: "Receives Stripe events",
  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("Event verified", { type: event.type });

    if (event.type === "payment_intent.succeeded") {
      await ctx.jelou.send({
        type: "text",
        to: event.data.object.metadata.phone,
        text: "We received your payment!",
      });
    }

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

Set the secret once:

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

The event your handler receives is already the Zod-validated body. The platform consumed the request body to validate it, so calling request.json() inside the handler throws — use the first parameter.

Supported providers

Verifier	Header	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` or `META_APP_SECRET`
`ctx.verifyHmac(request, opts)`	The one you name	`opts.secretEnv` or `opts.secret`

Stripe additionally rejects events older than 5 minutes, which stops someone from replaying a captured event.

Other services

For Twilio, GitHub, Slack or any service with an HMAC-SHA256 signature, use ctx.verifyHmac. The header is required because there is no default:

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

Rotate secrets

During a rotation, accept both the old and the new secret at once by comma-separating them:

jelou functions secrets set my-webhook STRIPE_WEBHOOK_SECRET=whsec_new,whsec_old

Once you confirm the provider is using the new one, go back to a single value.

Handle the failure

Verifiers throw WebhookVerificationError with a code telling you what happened:

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("Signature rejected", { code: err.code, provider: err.provider });
      return new Response(null, { status: 401 });
    }
    throw err;
  }

  return { received: true };
}

Code	Meaning
`missing_signature`	The request arrived with no signature header
`invalid_signature`	The signature does not match the body
`expired_timestamp`	The event is too old (Stripe)
`missing_secret`	You did not configure that provider’s secret

If you do not catch the error, the function responds with an error and the provider will retry the webhook. For Stripe and Shopify that is usually right only when the failure is transient; on an invalid signature it is better to return 401 and not retry.

Public functions

Webhooks need config.public: true so the external service can call them without Jelou credentials. That is exactly why signature verification is mandatory: it is the only access control left.

config: {
  public: true,      // the provider has no Jelou API key
  methods: ["POST"], // webhooks are always POST
  mcp: false,        // pointless as an AI tool
}

See public functions.

Testing

In tests, createMockContext() leaves every verifier throwing missing_secret. To exercise the rest of the handler, bypass verification:

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

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

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

// After running the handler you can inspect the recorded calls
verifiers.calls; // [{ method: "stripe", ... }]

See the testing guide.

Public functions

Receive requests without Jelou credentials.

Secrets

Store each provider’s secret.

Deferred runs

Book a follow-up when the webhook arrives.

Webhook receiver

Full copy-paste example.

Getting Started

Developer

Jelou CLI

Outbound Messaging

Management

Marketplace

Channels

Configuration

Billing

Stripe

Supported providers

Other services

Rotate secrets

Handle the failure

Public functions

Testing

Public functions

Secrets

Deferred runs

Webhook receiver

​Stripe

​Supported providers

​Other services

​Rotate secrets

​Handle the failure

​Public functions

​Testing

Public functions

Secrets

Deferred runs

Webhook receiver

Stripe

Supported providers

Other services

Rotate secrets

Handle the failure

Public functions

Testing