webhooks.receive()

Verify the Mesa webhook signature, validate the payload with the exported Zod schemas, and dispatch handlers registered with mesa.webhooks.on(...).

import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({
  privateKey: process.env.MESA_PRIVATE_KEY,
  webhookSecret: process.env.MESA_WEBHOOK_SECRET,
});

mesa.webhooks.on('push', async (event) => {
  console.log(event.repository?.name, event.data.updates.length);
});

export async function POST(request: Request) {
  await mesa.webhooks.receive(request);
  return new Response('ok');
}

Options

Request

required

Incoming request object containing the raw JSON body and x-mesa-signature header.

Constructor requirement

receive(...) requires webhookSecret in the Mesa constructor. If omitted, it throws MissingWebhookSecretError.

Signature format

The x-mesa-signature header contains query-style parts separated by commas, including t for timestamp and sha256 for the HMAC SHA-256 digest.

Response

Returns Promise<void> when verification, validation, and handler dispatch succeed.

Errors

MesaError

Thrown when webhookSecret was not configured.

MesaError

Thrown when the signature header is missing or malformed, the timestamp is outside the five-minute tolerance, the body is not JSON, or the payload fails schema validation.

Error

Thrown when one or more registered handlers reject after the webhook itself has been verified.

Schemas

The SDK exports WebhookEventSchema plus individual payload schemas such as PushPayloadSchema, RepoCreatedPayloadSchema, and ChangeCreatedPayloadSchema for callers that need standalone validation.

​Options

​Constructor requirement

​Signature format

​Response

​Errors

​Schemas