Conecta tu aplicación a una automatización

Envía un evento de aplicación cuando algo ocurra en tu sistema, como la creación de un pedido o la llegada de un pago. Un evento puede iniciar una ejecución, continuar una ejecución que lo esté esperando o cancelar una ejecución con una regla de cancelación coincidente. Cada automatización tiene una URL de evento para los tres usos.

Automations is in Early access. Your workspace permissions determine which actions you can perform.

Si no puedes abrir Automations o crear un borrador, consulta controles de acceso y edición del espacio de trabajo.

Configura el evento que inicia una ejecución

Crea una automatización con Event from your application como disparador.
Establece Event name, por ejemplo order.created. Los nombres distinguen entre mayúsculas y minúsculas y pueden contener letras, números, puntos, guiones bajos o guiones.
Define Event fields con los datos que envía tu aplicación. Para un pedido, añade un campo de tipo string llamado order_id. Los pasos posteriores pueden usar estos campos.
Publica la automatización. La pantalla de confirmación muestra How to start a run, con la URL del evento y un ejemplo de solicitud.

Para volver a encontrar los detalles de conexión, selecciona el disparador y haz clic en How to connect your application en la edición rápida. El editor expandido muestra los controles de conexión.

Simula un borrador o ejecuta la versión publicada

Usa Preview workflow con datos de ejemplo para simular tu borrador sin enviar mensajes ni modificar datos. Ejecutar el comando cURL, hacer clic en Send event… o usar Start run ejecuta la automatización publicada y puede realizar acciones reales. Los cambios del borrador, guardados o no, no se aplican a esas ejecuciones.

Publica la automatización antes de enviar eventos. Si no tiene una versión publicada, la solicitud se rechaza de inmediato; el evento no se encola ni se guarda para después. Los ejemplos del editor pueden reflejar cambios del borrador, así que publica esos cambios antes de enviar datos que dependan de ellos.

Copia la URL y envía un evento

Usa Copy request para obtener un comando cURL con la URL, las cabeceras y el cuerpo de ejemplo. Reemplaza los valores de ejemplo con los datos de tu aplicación.

La URL incluye los IDs del espacio de trabajo y de la automatización:

Ejemplo de código

POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>

Usa la URL completa copiada desde el panel. No necesitas una cabecera X-Workspace-Id. La opción de autenticación actual es No authentication: cualquier persona con esta URL puede enviar eventos. Guárdala en la configuración de tu servidor.

Para una automatización configurada para order.created, establece AUTOMATION_EVENT_URL con la URL copiada y envía:

Ejemplo de código

curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'

Establece type con el nombre del evento configurado y data con un objeto que coincida con los campos del evento. También puedes proporcionar occurred_at como una marca de tiempo RFC 3339; por defecto toma la hora en que llega el evento.

Una respuesta 202 Accepted con status: "queued" confirma que el evento está en cola. Bird genera el identificador del evento y lo devuelve como event_id. Abre la pestaña Runs de la automatización para inspeccionar la ejecución. La aceptación en la cola no confirma que el evento coincidió con un disparador ni que se inició una ejecución.

También puedes usar Send event… en el panel para enviar el ejemplo sin un terminal. Esto envía un evento real.

Continúa una ejecución que espera un evento

Un paso en espera usa la misma URL de automatización que el disparador. Su nombre de evento y subject_key identifican qué ocurrió y qué ejecución debe recibirlo.

En Automation settings, activa Skip overlapping runs y Use a business key. Establece Business key con un valor que identifique el pedido, la factura u otro objeto. Para el ejemplo de pedido, usa la expresión trigger.data.data.order_id.
Añade Wait for application event y configura su nombre de evento, campos del evento y tiempo de espera. Por ejemplo, espera order.paid con un campo string payment_id.
Publica, envía el evento inicial y espera hasta que su ejecución aparezca en Runs.
Envía el evento de seguimiento a la misma URL, con subject_key igual a la clave de negocio de la ejecución:

Ejemplo de código

{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}

subject_key es el valor de la clave de negocio, como order_123; no es el ID del evento ni el ID de la ejecución. La vista de conexión expandida del paso de espera muestra orientación para tu clave configurada.

Un evento coincidente se puede capturar después de que la ejecución comience, incluso antes de que llegue al paso en espera. Los eventos procesados antes de que exista una ejecución coincidente no se guardan para una ejecución futura. Una espera con filtro continúa solo cuando coinciden tanto los campos del evento como el filtro. La ejecución toma la ruta de tiempo de espera agotado si no se procesa ningún evento elegible antes de la fecha límite.

Las reglas de cancelación en Automation settings también usan esta URL. Una regla puede apuntar a todas las ejecuciones activas de la automatización o a la ejecución que coincida con subject_key. Configura un filtro para limitar qué ejecuciones cancela. La cancelación no puede deshacer una acción que ya ocurrió.

Versiones publicadas y automatizaciones en pausa

Las nuevas ejecuciones usan la versión activa cuando se procesa el evento. Las ejecuciones existentes conservan su versión original, incluidos sus campos de evento y condiciones de espera. Publicar un formato de evento modificado no actualiza las ejecuciones que ya comenzaron.

Pausar una automatización publicada detiene las nuevas ejecuciones. Los eventos aún pueden continuar o cancelar ejecuciones existentes mientras está en pausa.

Gestiona la entrega y los reintentos

Los eventos se procesan de forma asíncrona y pueden reintentarse o procesarse en un orden diferente. Espera a que la ejecución inicial exista antes de enviar un evento de seguimiento. El occurred_at de un evento no controla el orden de procesamiento, no extiende una espera ni previene un tiempo de espera agotado.

La protección contra reintentos es limitada. Si los registros de reintento expiran o se pierden, un evento puede procesarse de nuevo, potencialmente contra una versión más reciente o una ejecución activa diferente. Diseña tu aplicación para tolerar eventos duplicados.

Para activar la protección contra reintentos, envía un Idempotency-Key en el primer intento y reutilízalo con la misma URL y el mismo cuerpo sin cambios en los reintentos. Usa una clave nueva para cada solicitud nueva. Una repetición devuelve el mismo event_id. La guía de idempotencia explica la ventana limitada de repetición y las respuestas de conflicto.

Soluciona problemas de un evento

La solicitud devuelve 4xx: Revisa los detalles de error de la respuesta, la URL y los campos obligatorios type y el objeto data. Envía Content-Type: application/json. El cuerpo completo de la solicitud debe caber en 25 KB (25.000 bytes); los cuerpos más grandes devuelven 413.
La automatización no se ha publicado: Publícala antes de enviar un evento. El evento rechazado no se retiene; envía una nueva solicitud después de publicar.
La solicitud devuelve 202 pero no se inicia ninguna ejecución: Comprueba que la automatización esté activa, que el nombre del evento coincida con su trigger y que los datos coincidan con los campos de evento publicados. La protección contra solapamiento puede omitir una nueva ejecución mientras otra esté activa. Comprueba también la cuota mensual de ejecuciones; las ejecuciones omitidas al alcanzar el límite no se encolan para el mes siguiente.
La ejecución se queda en un paso en espera: Comprueba el nombre del evento, la clave de negocio exacta, los campos de datos, el filtro y el tiempo de espera. Usa el formato de evento de la versión publicada original de la ejecución.
Un reintento devuelve un conflicto: Reintenta con la clave original y la solicitud sin cambios. Si pretendes enviar un evento diferente, usa una clave nueva.

La respuesta de error de la solicitud se verifica antes de encolar. Los datos del evento se verifican contra el disparador, la espera y las reglas de cancelación durante el procesamiento, por lo que un evento encolado puede no coincidir con ninguno de ellos.

Próximos pasos

Abre Automations para configurar y publicar tu flujo de trabajo.
Gestiona reintentos idempotentes en tu aplicación.
Espera un evento en un flujo de trabajo en ejecución.
Explora las guías de Automations.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Guía de implementaciónPreview your first automation