Webhooks

Orkestra soporta webhooks en ambas direcciones. Outbound: te avisamos cuando algo cambia. Inbound: tu servicio externo crea tareas o actualiza estados. Ambos disponibles desde el plan Organization.

Outbound webhooks

Cuando un evento ocurre en tu organización (tarea creada, estado cambiado, comentario añadido, etc.), Orkestra envía un POST a la URL que configures. Los eventos están firmados con HMAC para que puedas verificar que vienen de Orkestra.

Eventos soportados

Los eventos principales que puedes suscribir:

• task.created — nueva tarea creada
• task.updated — cualquier campo actualizado
• task.state_changed — cambio de estado en workflow
• task.assigned — asignación o reasignación
• task.deleted — tarea eliminada
• project.created, project.archived, project.deleted
• wiki.page_updated — edición de página de wiki
• comment.created — nuevo comentario en tarea o wiki
• member.joined, member.removed

Formato del payload

Cada webhook recibe un JSON con esta estructura:

• id — ID único del evento (para idempotencia)
• type — nombre del evento (ej: task.state_changed)
• createdAt — timestamp ISO 8601
• organizationId — ID de la org donde ocurrió
• data — objeto con el recurso afectado y, si aplica, previous con el estado anterior

Verificación HMAC

Cada request incluye el header X-Orkestra-Signature con un HMAC-SHA256 del body usando tu webhook secret. Para verificar:

1. Toma el body crudo del request (sin parsear).
2. Calcula HMAC-SHA256(body, tu_secret).
3. Compara con el header en tiempo constante (usa crypto.timingSafeEqual en Node).

Retry inteligente

Orkestra reintenta entregas fallidas con esta lógica:

• 5xx / timeout: reintento con backoff exponencial (1s, 5s, 30s, 2min, 10min, 1h).
• 4xx (excepto 429): fallo permanente, no se reintenta. Verás el error en el log.
• 429: respeta Retry-After si lo envías, o aplica backoff exponencial.
• Tras 6 intentos fallidos, el webhook se marca como fallido y se notifica al admin.

Inbound webhooks

Los inbound webhooks te permiten crear tareas o actualizar estados desde servicios externos. Son compatibles con Zapier y Make, o puedes llamarlos directamente desde tu código.

Configuración

Desde Ajustes → Webhooks entrantes → Nuevo:

1. Elige el proyecto destino.
2. Define el mapeo de campos (ej: titulo del payload → title de Orkestra).
3. Copia la URL y la API key generadas.
4. Configura tu servicio externo para hacer POST con el payload mapeado.

Auth

Los webhooks entrantes se autentican con el header X-Orkestra-Api-Key. La clave es única por webhook y revocable. Se almacena hasheada con SHA-256.

Monitoring

Todos los webhooks (entrantes y salientes) tienen un log con los últimos 30 días de actividad: status, latency, payload, respuesta. Útil para debugging cuando algo no funciona.