Webhooks

Los webhooks envían una solicitud HTTPS firmada a tu servidor cuando algo ocurre en Sift. Un endpoint puede suscribirse a eventos de acciones, como una etiqueta añadida o un cambio de estado. Una regla de notificación también puede enviar a un endpoint.

De un vistazoCopy Anchor Link

ConfigurarloCopy Anchor Link

1. Ve a Configuración → Acceso de desarrollador → Webhooks.
2. Selecciona Nuevo endpoint. Escribe un nombre y una URL HTTPS pública, y elige los eventos que quieres recibir.
3. Copia el secreto de firma. Sift solo lo muestra una vez.
4. Opcional: abre el endpoint y elige una búsqueda guardada en Solo para acciones que coincidan. No se envían eventos de otras acciones.
5. Selecciona Enviar prueba. El endpoint debe responder con un estado entre 200 y 299.

Para enviar desde una regla, abre Configuración → Workflows → Notificaciones, edita una notificación y selecciona el endpoint en Webhooks.

EventosCopy Anchor Link

El cuerpo de un evento tiene este aspecto. change describe lo que ocurrió. action es el estado de la acción cuando Sift creó el evento; un reintento envía el mismo cuerpo.

{
  "id": "evt_qy1b3lsr19x0qjoljxgiys9k",
  "type": "action.tag_added",
  "apiVersion": "2026-11-01",
  "occurredAt": "2026-10-28T18:55:19.175Z",
  "orgId": "org_...",
  "data": {
    "action": {
      "id": "act_...",
      "displayId": "ACME-1842",
      "url": "https://app.getsift.ai/app/record/act_...?entity=action",
      "status": "OPEN",
      "platform": "CUSTOM_API",
      "channel": "social-ai-api-DEV",
      "queueId": "queue_...",
      "assigneeId": null,
      "externalId": "post-184",
      "sourceId": "src_...",
      "tags": [{ "id": "tag_...", "name": "Remove post" }],
      "customFields": []
    },
    "change": {
      "tag": { "id": "tag_...", "name": "Remove post" },
      "actor": { "type": "USER", "id": "user_...", "name": "Dana Kim" }
    }
  }
}

apiVersion es una fecha. Pueden aparecer campos nuevos sin una fecha nueva. Un cambio incompatible llega con una fecha nueva.

Formato de las notificaciones de reglasCopy Anchor Link

Sift envía un sobre JSON. El objeto data contiene la notificación de workflow.

{
  "subjectType": "workflow_webhook",
  "subjectId": "organization",
  "orgId": "org_...",
  "deliveredAt": "2026-09-01T18:02:11.000Z",
  "data": {
    "id": "workflow-notification:...",
    "type": "workflow.notification",
    "version": 1,
    "occurredAt": "2026-09-01T18:02:11.000Z",
    "orgId": "org_...",
    "message": "Mensaje personalizado opcional",
    "workflow": {
      "id": "wf_...",
      "executionId": "wfx_...",
      "triggerId": "trg_...",
      "name": "Escalar señales de compra"
    },
    "action": {
      "id": "act_...",
      "easyId": "ACME-1842",
      "status": "OPEN",
      "queueId": "queue_...",
      "assigneeId": null,
      "platform": "x",
      "externalId": "feedback-184",
      "sourceId": "src_feedback",
      "customFields": [
        {
          "fieldName": "decision",
          "displayName": "Decisión",
          "fieldType": "string",
          "value": "Eliminar",
          "provenance": { "source": "human", "at": "2026-09-01T18:01:40.000Z" }
        }
      ]
    }
  }
}

action.customFields enumera los valores de campos personalizados del acción en el momento en que se disparó el workflow, una entrada por valor, con el nombre y el tipo actuales del campo. Los campos sin valor no aparecen. Solo aparecen los campos registrados en Settings → Custom fields; las claves internas de Sift nunca aparecen. action.externalId es el id del elemento en el sistema de origen y action.sourceId es el id de la fuente de Custom API; ambos son null en otras plataformas. Un suscriptor puede actuar sobre un cambio de etiqueta sin una segunda lectura.

action.status es el estado operativo del acción, tal como se muestra en la bandeja de entrada: OPEN, RESPONDED, WAITING_FOR_USER, RESOLVED, CLOSED, DISMISSED, SNOOZED u otro token de estado personalizado como CUSTOM_STATUS_1. Es null cuando el acción no tiene estado operativo. action.easyId es el ID del acción con el prefijo de tu organización, tal como se muestra en la app.

Algunos campos pueden faltar cuando no se aplican a la action o al workflow. Pueden aparecer campos adicionales en la versión 1. Usa el campo version antes de depender de una nueva versión del payload.

Verificar la firmaCopy Anchor Link

Cada solicitud lleva cabeceras de Standard Webhooks. Usa cualquier biblioteca de Standard Webhooks con el secreto de firma del endpoint.

webhook-id: evt_...                 (estable entre reintentos; úsalo para descartar duplicados)
webhook-timestamp: 1793210097       (segundos; rechaza solicitudes de más de cinco minutos)
webhook-signature: v1,<base64> v1,<base64>
x-sift-event: action.tag_added
x-sift-signature: sha256=<hex>      (HMAC-SHA256 del cuerpo, para receptores anteriores a Standard Webhooks)

import { Webhook } from "standardwebhooks"

export function verifySiftWebhook(rawBody, headers, secret) {
  // Lanza un error si la firma o la marca de tiempo no son válidas.
  return new Webhook(secret).verify(rawBody, headers)
}

Verifica el cuerpo sin procesar antes de analizar el JSON. Después de rotar un secreto, el anterior también firma durante 24 horas, así que webhook-signature puede llevar dos firmas. Acepta la solicitud si una coincide.

Entrega y reintentosCopy Anchor Link

Sift envía un evento alrededor de un segundo después del cambio. La entrega es al menos una vez: usa webhook-id para descartar duplicados. Los eventos de una acción llegan a un endpoint en el orden en que ocurrieron.

Sift reintenta los fallos de red, los tiempos de espera y las respuestas 408, 425, 429 y 5xx durante un máximo de 24 horas. Las demás respuestas 4xx son definitivas. Un 410 Gone desactiva el endpoint. Devuelve una respuesta 2xx solo cuando tu sistema acepte el evento.

Cada endpoint muestra sus envíos de los últimos días. Selecciona Reenviar en un evento fallido para enviar de nuevo el mismo cuerpo. Si todos los envíos fallan durante cinco días, Sift desactiva el endpoint y avisa por correo a tus administradores. Vuelve a activarlo desde el endpoint.

Seguridad del endpointCopy Anchor Link

Los endpoints de webhook deben usar HTTPS y resolver solo a direcciones públicas. Sift rechaza URLs con credenciales, direcciones privadas o reservadas, resultados DNS públicos y privados combinados y redirecciones.

ConsejosCopy Anchor Link

• Guarda el secreto de firma en tu gestor de secretos.
• Responde rápidamente. Procesa el trabajo largo después de devolver una respuesta 2xx.
• Usa la webhook-id como clave única de tu handler.
• Desactiva el destino antes de un mantenimiento planificado si no quieres reintentos.
• Rota el secreto cuando un miembro del equipo o una integración pierda acceso.

RelacionadoCopy Anchor Link