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

# Disparar una automatización desde tu sistema (webhook entrante)

> Conecta tu sitio o tu sistema a una automatización de Asistian: dónde está la URL, dónde está el secreto de firma y cómo firmar cada envío.

Una automatización puede arrancar cuando **tu sistema** avisa a Asistian: un
pedido nuevo en tu tienda, un pago aprobado, un formulario enviado desde tu
sitio. El disparador se llama **Webhook entrante** y te da una URL a la que tu
sistema manda un `POST` con JSON.

<Note>
  Esta página es para el disparador **Webhook entrante** de una automatización.
  Si lo que quieres es que un formulario de tu sitio cree conversaciones o
  contactos, el camino más simple es el **canal Webhook**, que se protege
  con una [clave secreta](/mintlify/canales/webhook-clave-secreta) en lugar de
  una firma.
</Note>

## Crear el webhook

<Steps>
  <Step title="Crea la automatización">
    Ve a **Configuración → Automatizaciones → Crear Automatización**. En el
    primer nodo (el del evento), elige **Webhook entrante** como tipo de evento.
  </Step>

  <Step title="Agrega al menos una acción">
    Un webhook entrante sin acciones no se guarda: define qué debe pasar cuando
    lleguen los datos (dejar una nota, asignar un agente, mover de etapa…).
  </Step>

  <Step title="Guarda la automatización">
    Al guardar se generan la **URL** y el **secreto de firma**. Antes de guardar
    todavía no existen.
  </Step>

  <Step title="Copia la URL y el secreto">
    Vuelve a abrir el nodo del evento. Ahí están, uno debajo del otro:

    * **URL de Webhook de Producción** — la que configuras en tu sistema.
    * **Requerir Firma** — encendido por defecto.
    * **Secreto de firma** — oculto; usa el ícono del ojo para verlo y el de
      copiar para llevártelo.
  </Step>
</Steps>

## Firmar cada envío

Con **Requerir Firma** encendido, Asistian rechaza con `401` cualquier petición
que no traiga el header `X-Webhook-Signature`.

La firma tiene el formato `sha256=<hmac>`, donde el HMAC es SHA-256 del **cuerpo
exacto que envías**, usando el secreto como llave:

```js theme={null}
import { createHmac } from 'node:crypto';

const body = JSON.stringify(payload);
const signature = 'sha256=' + createHmac('sha256', SECRET)
  .update(body)
  .digest('hex');

await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature,
    'Idempotency-Key': idDelEventoEnTuSistema,
  },
  body,
});
```

En PHP:

```php theme={null}
$body = json_encode($payload);
$signature = 'sha256=' . hash_hmac('sha256', $body, $secreto);
```

<Warning>
  Firma el cuerpo **tal cual lo envías**. Si serializas el JSON una vez para
  firmar y otra para mandar, y las dos cadenas difieren aunque sea por el orden
  de las llaves o un espacio, la firma no coincide y el envío falla con `401`.
  Es el error más común: reutiliza la misma variable, como en el ejemplo.
</Warning>

## Qué responde Asistian

| Respuesta | Qué significa                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `202`     | Recibido y encolado. Las acciones corren en segundo plano: el resultado **no** viene en esta respuesta |
| `401`     | Falta la firma, o no coincide con el secreto                                                           |
| `403`     | La automatización está desactivada                                                                     |
| `404`     | La URL no corresponde a ninguna automatización                                                         |
| `409`     | La automatización llegó a su límite de ejecuciones                                                     |
| `422`     | La automatización no tiene acciones configuradas                                                       |

Como el trabajo es asíncrono, revisa el resultado en el **Historial** de la
automatización, no en la respuesta del `POST`.

## No repetir un evento dos veces

Manda un header `Idempotency-Key` con el identificador del evento en tu sistema.
Si reintentas con el mismo valor, Asistian reconoce la entrega y no vuelve a
ejecutar las acciones. También se acepta `X-Webhook-Id`. Si no mandas ninguno,
Asistian deriva la clave del cuerpo exacto de la petición, así que dos eventos
legítimamente idénticos se tomarían como uno solo: cuando eso sea posible, manda
la clave explícita.

## Regenerar el secreto

En el mismo nodo, **Regenerar Secreto** genera uno nuevo. El anterior deja de
funcionar de inmediato y las peticiones firmadas con él empiezan a recibir `401`,
así que actualiza tu sistema en ese momento. La acción pide verificación en dos
pasos.

<Note>
  Si la automatización se creó hace tiempo y todavía no tiene secreto, el mismo
  lugar muestra el botón **Generar secreto**.
</Note>

## Apagar la firma

Puedes apagar **Requerir Firma** si tu sistema no puede calcular un HMAC. Ten en
cuenta lo que eso significa: **cualquiera que conozca la URL puede disparar la
automatización**. Hazlo solo si la URL vive en tu servidor y nunca en el
navegador.

## Probar antes de conectar

**Probar Webhook**, en el mismo nodo, sirve **antes de guardar**: deja la URL a
la escucha, tú mandas un envío desde tu sistema y Asistian captura el payload
—sin ejecutar acciones— para que puedas usar sus campos en las condiciones y en
las acciones.

<Warning>
  Una vez que la automatización está guardada y **activa**, no hay modo de
  prueba: todo envío a esa URL se ejecuta de verdad. Si necesitas probar sin
  efectos, desactiva la automatización antes: mientras esté inactiva, Asistian
  captura el payload y responde `403` sin ejecutar nada.
</Warning>