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

# Webhooks: eventos de leads en tiempo real | DeltaLead

> Los webhooks de DeltaLead envían solicitudes POST en tiempo real a un endpoint HTTPS cuando se crea, califica o asigna un lead, o cuando se agenda una cita.

Los webhooks de DeltaLead entregan solicitudes HTTP POST al servidor en el mismo momento en que ocurre algo relevante en la cuenta: llega un lead nuevo, un agente de IA califica un lead o se agenda un test drive. En lugar de consultar la API de forma periódica, los sistemas reciben los datos del evento en tiempo real y sin latencia adicional, lo que permite disparar flujos posteriores, actualizar una base de datos propia o avisarle al equipo de ventas en el instante en que aparece un lead caliente.

## Registrar un endpoint de webhook

<Steps>
  <Step title="Abrir la configuración de webhooks">
    En el panel de DeltaLead, ir a **Configuración → Webhooks → Agregar endpoint**. Como alternativa, se puede llamar directamente a `POST /v1/webhooks` desde la API.
  </Step>

  <Step title="Indicar la URL del endpoint">
    Se indica la URL HTTPS completa del servidor que va a recibir los eventos. Los endpoints con HTTP simple no se aceptan: DeltaLead exige un certificado TLS válido.
  </Step>

  <Step title="Seleccionar los eventos">
    Se eligen los tipos de evento a los que conviene suscribirse. Suscribirse solo a los eventos que la integración necesita reduce el tráfico innecesario hacia el servidor. La [referencia completa de eventos](/api-reference/webhooks/events) enumera todos los tipos disponibles.
  </Step>

  <Step title="Guardar y copiar el secreto">
    Al guardar, DeltaLead genera un secreto de firma HMAC-SHA256 para el endpoint. Hay que copiarlo de inmediato: se muestra una sola vez. Conviene guardarlo de forma segura en las variables de entorno de la aplicación y usarlo para verificar cada solicitud entrante.
  </Step>
</Steps>

## Estructura del payload

Todo POST de webhook que DeltaLead envía al endpoint comparte la misma estructura de nivel superior, sin importar el tipo de evento.

<ResponseField name="event" type="string">
  Tipo de evento que originó esta entrega, por ejemplo `lead.qualified`.
</ResponseField>

<ResponseField name="timestamp" type="string">
  Marca de tiempo ISO 8601 del momento en que ocurrió el evento en la plataforma de DeltaLead.
</ResponseField>

<ResponseField name="organization_id" type="string">
  ID de la organización de DeltaLead asociada al evento.
</ResponseField>

<ResponseField name="data" type="object">
  Payload específico del evento. Los campos que contiene `data` varían según el tipo de evento. La [referencia de eventos](/api-reference/webhooks/events) incluye los esquemas completos.
</ResponseField>

```json lead.qualified event theme={null}
{
  "event": "lead.qualified",
  "timestamp": "2024-11-07T15:30:00Z",
  "organization_id": "org_xyz789",
  "data": {
    "id": "lead_abc123",
    "name": "María García",
    "phone": "+5491155551234",
    "score": 92,
    "intent": "purchase_30_days",
    "vehicle_interest": "Toyota Hilux SRX 2024",
    "channel": "whatsapp",
    "status": "qualified"
  }
}
```

## Verificación de firmas de webhook

DeltaLead firma cada solicitud de webhook para demostrar que el payload salió de su plataforma. La firma viaja en la cabecera de solicitud `X-DeltaLead-Signature` como un digest HMAC-SHA256 codificado en hexadecimal del cuerpo crudo de la solicitud, calculado con el secreto de firma del endpoint.

La firma debe verificarse siempre antes de procesar el payload de un webhook. Omitir este paso deja el endpoint expuesto a solicitudes falsificadas.

<CodeGroup>
  ```javascript Node.js theme={null}
  const crypto = require('crypto');

  function verifyWebhook(rawBody, signatureHeader, secret) {
    const expected = crypto
      .createHmac('sha256', secret)
      .update(rawBody)
      .digest('hex');
    return crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signatureHeader)
    );
  }
  ```

  ```python Python theme={null}
  import hmac
  import hashlib

  def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
      expected = hmac.new(
          secret.encode('utf-8'),
          raw_body,
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(expected, signature_header)
  ```

  ```php PHP theme={null}
  function verifyWebhook(string $rawBody, string $signatureHeader, string $secret): bool {
      $expected = hash_hmac('sha256', $rawBody, $secret);
      return hash_equals($expected, $signatureHeader);
  }
  ```
</CodeGroup>

<Note>
  Conviene usar siempre una comparación de tiempo constante (como `crypto.timingSafeEqual` en Node.js o `hmac.compare_digest` en Python) para evitar ataques de temporización contra la verificación de la firma.
</Note>

## Respuesta a los webhooks

El endpoint debe devolver un código de estado HTTP `2xx` dentro de los **10 segundos** de recibida la entrega. DeltaLead interpreta cualquier respuesta que no sea `2xx` —o una solicitud que expire por tiempo— como una entrega fallida.

<CardGroup cols={2}>
  <Card title="Política de reintentos" icon="rotate">
    DeltaLead reintenta las entregas fallidas hasta **3 veces** con retroceso exponencial. Los intervalos de reintento son de aproximadamente 1 minuto, 5 minutos y 30 minutos después del fallo inicial.
  </Card>

  <Card title="Idempotencia" icon="shield-check">
    Como los reintentos pueden generar entregas duplicadas, el manejador debe diseñarse de forma idempotente. El campo `data.id` sirve para descartar los eventos ya procesados.
  </Card>
</CardGroup>

<Tip>
  Durante el desarrollo local, una herramienta de túnel como [ngrok](https://ngrok.com) permite exponer el servidor de localhost a internet y recibir eventos reales de webhook de DeltaLead sin necesidad de desplegar en un servidor público.
</Tip>

La [referencia de eventos de webhook](/api-reference/webhooks/events) contiene la lista completa de tipos de evento y sus esquemas de payload.