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

# Webhooks

> Configura, recibe y autentica Webhooks de Esolbay

## Flujo

1. Configuras un endpoint público en tu sistema.
2. En el Panel de Esolbay registras la URL del webhook.
3. Esolbay envía eventos (p. ej. `order.create`) autenticados por cabecera.
4. Tu servicio valida la cabecera y procesa el evento.

## Configuración en el Panel

Ve a <a href="https://prod.esolbay.com/platform/organization/apikey" target="_blank" rel="noopener">Panel → API Key & Webhooks</a> y crea un webhook:

* Label descriptivo
* URL (POST pública)
* Eventos habilitados

## Encabezados

* `x-api-key` (string): API Key de tu organización.
* `x-esolbay-event-id` (string): recomendado para idempotencia.
* `x-esolbay-timestamp` (ISO8601): recomendado para protección anti-replay.

## Validación

Valida que el valor de `x-api-key` coincida con tu API Key de Esolbay almacenada en tu entorno.

<CodeGroup>
  ```javascript Node.js theme={null}
  import express from 'express';

  const app = express();
  app.post('/webhooks/esolbay', express.text({ type: '*/*' }), (req, res) => {
    const providedKey = req.header('x-api-key');
    const expectedKey = process.env.ESOLBAY_API_KEY;
    if (!providedKey || providedKey !== expectedKey) {
      return res.status(401).send('Unauthorized');
    }
    // Opcional: usar x-esolbay-event-id para idempotencia
    // const eventId = req.header('x-esolbay-event-id');
    return res.status(200).send('ok');
  });
  ```
</CodeGroup>

<Warning>
  Usa el cuerpo RAW (texto) si necesitas procesarlo como texto antes de parsearlo.
</Warning>

## Reintentos e idempotencia

* Usa `x-esolbay-event-id` como clave idempotente (no procesar el mismo id dos veces).
* Rechaza eventos con `x-esolbay-timestamp` muy antiguos (p. ej. > 5 minutos).

## Catálogo de eventos

Los esquemas de payload están documentados en <a href="/api-reference/openapi.json">OpenAPI</a> (ver `x-webhooks`).