> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# webhooks.receive()

> Verify an incoming webhook request and dispatch registered handlers.

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

```ts theme={null}
import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({
  apiKey: process.env.MESA_API_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

<ParamField path="request" type="Request" required>
  Incoming request object containing the raw JSON body and `x-mesa-signature` header.
</ParamField>

## 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

<ResponseField name="MissingWebhookSecretError" type="MesaError">
  Thrown when `webhookSecret` was not configured.
</ResponseField>

<ResponseField name="MesaWebhookVerificationError" type="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.
</ResponseField>

<ResponseField name="AggregateError" type="Error">
  Thrown when one or more registered handlers reject after the webhook itself has been verified.
</ResponseField>

## Schemas

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