Webhooks

Los webhooks le permiten recibir callbacks HTTP en tiempo real cuando ocurren eventos en su organización. Puede suscribirse a tipos de eventos específicos y graph8 enviará un payload JSON firmado mediante POST a su endpoint.

Eventos disponibles

GET /webhooks/events

Devuelve todos los tipos de eventos a los que puede suscribirse.

Ejemplo

cURL

curl "https://api.graph8.com/api/v1/webhooks/events" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": [
    { "event": "campaign.created" },
    { "event": "campaign.updated" },
    { "event": "campaign.deleted" },
    { "event": "campaign.launched" },
    { "event": "campaign.status_changed" },
    { "event": "document.created" },
    { "event": "document.updated" },
    { "event": "document.generated" },
    { "event": "intelligence.completed" },
    { "event": "research.completed" },
    { "event": "company.enriched" },
    { "event": "person.enriched" },
    { "event": "company_intelligence.completed" }
  ]
}

Listar webhooks

GET /webhooks

Devuelve todas las suscripciones de webhook de su organización.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`is_active`	boolean	—	Filtrar por estado activo

curl "https://api.graph8.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/webhooks",
    headers=HEADERS
)

Respuesta

{
  "data": [
    {
      "id": "wh-abc",
      "name": "CRM Sync",
      "url": "https://example.com/webhooks/graph8",
      "events": ["campaign.created", "campaign.updated"],
      "is_active": true,
      "created_at": "2026-02-20T10:00:00",
      "updated_at": "2026-02-20T10:00:00"
    }
  ]
}

Crear webhook

POST /webhooks

Crea una nueva suscripción de webhook. El secret de firma se devuelve una sola vez en la respuesta; guárdelo de forma segura.

Máximo 10 webhooks activos por organización.

Devuelve 201 Created.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`url`	string	Sí	URL de destino para la entrega
`events`	string[]	Sí	Tipos de eventos a los que suscribirse
`name`	string	No	Nombre legible

Ejemplo

cURL
Python

curl -X POST "https://api.graph8.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/graph8",
    "events": ["campaign.created", "campaign.launched"],
    "name": "CRM Sync"
  }'

response = requests.post(
    f"{BASE_URL}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://example.com/webhooks/graph8",
        "events": ["campaign.created", "campaign.launched"],
        "name": "CRM Sync"
    }
)
secret = response.json()["data"]["secret"]  # Store this!

Respuesta

{
  "data": {
    "id": "wh-abc",
    "name": "CRM Sync",
    "url": "https://example.com/webhooks/graph8",
    "events": ["campaign.created", "campaign.launched"],
    "is_active": true,
    "secret": "whsec_a1b2c3d4e5f6..."
  }
}

Verificación de firmas

Cada entrega incluye un encabezado X-Webhook-Signature. Verifíquelo con HMAC-SHA256:

import hashlib, hmac

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Obtener webhook

GET /webhooks/{webhook_id}

Devuelve los detalles del webhook. El secret no se incluye en la respuesta.

Actualizar webhook

PATCH /webhooks/{webhook_id}

Actualización parcial: envíe solo los campos que desea modificar.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`url`	string	URL de destino
`events`	string[]	Tipos de eventos
`name`	string	Nombre legible
`is_active`	boolean	Activar o desactivar

Eliminar webhook

DELETE /webhooks/{webhook_id}

Devuelve 204 No Content cuando se completa con éxito.

Listar entregas

GET /webhooks/{webhook_id}/deliveries

Devuelve los intentos de entrega de un webhook, con paginación.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`page`	integer	1	Número de página
`limit`	integer	50	Elementos por página (máx. 200)
`status`	string	—	Filtrar por estado de entrega (`success`, `failed`, `pending`)

Ejemplo

cURL

curl "https://api.graph8.com/api/v1/webhooks/wh-abc/deliveries" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": [
    {
      "id": "del-1",
      "event": "campaign.created",
      "status": "success",
      "attempts": 1,
      "max_attempts": 3,
      "response_code": 200,
      "error_message": null,
      "created_at": "2026-02-25T10:00:00",
      "completed_at": "2026-02-25T10:00:01"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "has_next": false
  }
}

Las entregas fallidas se reintentan hasta 3 veces con intervalos crecientes (10s, 60s, 300s).