Webhooks

En vez de preguntar cada poco si hay algo nuevo, dinos una URL y te avisamos: cuando se crea o cambia una obra o un presupuesto, se adjudica un presupuesto, entra una factura o un albarán…

Cómo es un aviso

Un POST con un JSON, firmado con el secreto del webhook:

http

POST /buildnexion/webhook HTTP/1.1
Host: tu-servidor.es
Content-Type: application/json
User-Agent: BuildNexion-Webhooks/1.0
X-BuildNexion-Event: estimate.awarded
X-BuildNexion-Delivery: d9e4a7b1-3f6c-4e28-a05d-6b2c8f1e9a37
X-BuildNexion-Signature: sha256=5d1f0c9e…

{
  "event": "estimate.awarded",
  "created_at": "2026-08-20T10:14:23.020Z",
  "organization_id": "5e8a2f61-9d4b-4c07-b3e1-a7c6d0f2b948",
  "data": {
    "estimate_id": "2b8e4d10-7c3a-4f5e-8d21-0a9b6c3e1f47",
    "project_id": "6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21",
    "code": "2026-014"
  }
}

Cuerpo

Parámetro	Tipo	Descripción
event string	string	El evento (ver el catálogo).
created_at datetime	datetime	Cuándo ocurrió. Va dentro de lo firmado.
organization_id uuid	uuid	Tu organización.
data object	object	Lo que ha pasado. Depende del evento.

Cabeceras

Parámetro	Tipo	Descripción
X-BuildNexion-Event string	string	El evento (igual que event).
X-BuildNexion-Delivery string	string	Id de la entrega. Es el mismo en todos los reintentos: úsalo para no procesar dos veces lo mismo.
X-BuildNexion-Signature string	string	sha256= y el HMAC-SHA256 del cuerpo con tu secreto. Ver Verificar la firma.

Entrega y reintentos

El aviso sale en el momento en que pasa la acción.
Tu servidor tiene que responder con un 2xx en menos de 8 segundos. Responde enseguida y procesa después.
Cualquier otra cosa cuenta como fallo: un error, un tiempo de espera agotado o una redirección (no las seguimos).
Si falla, se reintenta a los 5 minutos y, si vuelve a fallar, a los 30 minutos. Tras el tercer intento fallido se da por perdido; el último error se ve en la app, en el webhook.
No garantizamos el orden, y un mismo aviso puede llegar más de una vez. Para quedarte con el estado bueno, pide el objeto por la API cuando te llegue el aviso.

Los reintentos llevan el mismo contenido, pero el JSON puede venir con las claves en otro orden. La firma siempre corresponde al cuerpo tal como llega: verifícala sobre el cuerpo en crudo.

Dar de alta un webhook

En la app, en Configuración → Integraciones → API REST y Webhooks (solo administradores), o por API con una key con el permiso write:webhooks.

La URL tiene que ser pública (https:// recomendado). No se admiten direcciones internas: localhost, IPs privadas o de servicios de metadatos.

Crear

POST/api/v1/webhookswrite:webhooks

Cuerpo (JSON)

Parámetro	Tipo	Descripción
url* string	string	URL pública http(s) de tu servidor.
events* string[]	string[]	Eventos a los que te suscribes (al menos uno).
secret string	string	Tu propio secreto (16 caracteres o más). Si no lo pasas, se genera uno (whsec_…).
active boolean	boolean	false para crearlo en pausa. Por defecto, true.

curl -X POST https://app.buildnexion.com/api/v1/webhooks \
  -H "Authorization: Bearer $BUILDNEXION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.es/buildnexion/webhook",
    "events": ["project.created", "project.updated", "estimate.awarded"]
  }'

Respuesta

{
  "data": {
    "id": "7b1d9e42-a6c3-4085-9f2e-c5a8d3b0e761",
    "url": "https://tu-servidor.es/buildnexion/webhook",
    "events": [
      "project.created",
      "project.updated",
      "estimate.awarded"
    ],
    "active": true,
    "last_success_at": null,
    "last_error": null,
    "created_at": "2026-10-08T09:12:44.501+00:00",
    "secret": "whsec_6b1e…"
  }
}

El secret solo se devuelve al crear el webhook. Guárdalo: lo necesitas para verificar la firma.

Listar

GET/api/v1/webhookswrite:webhooks

Tus webhooks, con last_success_at y last_error (sin el secreto).

curl "https://app.buildnexion.com/api/v1/webhooks" \
  -H "Authorization: Bearer $BUILDNEXION_API_KEY"

Probar

POST/api/v1/webhooks/{id}/testwrite:webhooks

Envía al momento un evento webhook.test firmado y te dice qué respondió tu servidor: { ok, status, body }, o { ok: false, error } si no se pudo conectar. También se puede probar desde la app.

Borrar

DELETE/api/v1/webhooks/{id}write:webhooks

Responde 204 sin cuerpo. Para pausarlo sin borrarlo, desactívalo en la app.

Sigue con el catálogo de eventos y cómo verificar la firma.