BuildNexion

Webhooks

Los webhooks te permiten recibir notificaciones en tu servidor cada vez que algo cambia en BuildNexion. Más eficiente que hacer polling a la API.

Cómo funciona

  1. Registras una URL HTTPS de tu servidor.
  2. Eliges los eventos que te interesan (invoice.created, budget.accepted…).
  3. BuildNexion te envía un POST con el payload JSON cada vez que ocurre uno.
  4. Tu servidor responde 2xx en menos de 10 s. Si no, reintentamos.

Registrar un endpoint

POST/v1/webhooks

Body

ParámetroTipoDescripción
url*stringURL HTTPS donde recibirás los eventos.
events*string[]Lista de eventos. Ver el catálogo completo.
curl -X POST https://api.buildnexion.com/v1/webhooks \
  -H "Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://tu-servidor.com/buildnexion/webhook",
    "events": ["invoice.created", "budget.accepted"]
  }'

La respuesta incluye el secret que usarás para verificar las firmas HMAC:

json
{
  "id":     "wh_5tQpRn",
  "url":    "https://tu-servidor.com/buildnexion/webhook",
  "events": ["invoice.created", "budget.accepted"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "created_at": "2026-05-25T10:30:00.000Z"
}
El secret sólo se devuelve en el momento de la creación. Guárdalo en tu gestor de secretos. Si lo pierdes, debes rotarlo desde el panel.

Estructura del payload

json
POST /buildnexion/webhook
BuildNexion-Event:     invoice.created
BuildNexion-Delivery:  evt_8gpQ2nL
BuildNexion-Signature: t=1716629400,v1=4f3a2b1c0d…
Content-Type:          application/json

{
  "id":         "evt_8gpQ2nL",
  "type":       "invoice.created",
  "created_at": "2026-05-25T10:30:00.000Z",
  "organization_id": "org_91pQyKn",
  "data": {
    "object": {
      "id":              "inv_W3pNxL2YqAt",
      "project_id":      "prj_8GcyLwT4mPq",
      "provider_id":     "prov_4kqRpBn",
      "invoice_number":  "F-2026-00128",
      "total_amount":    300141,
      "currency":        "EUR"
    }
  }
}

Reintentos

Si tu servidor responde con un código distinto de 2xx (o tarda más de 10 s), reintentamos con backoff exponencial:

  • Intento 2: a los 30 segundos
  • Intento 3: a los 5 minutos
  • Intento 4: a la hora
  • Intento 5: a las 6 horas
  • Intento 6: a las 24 horas (último)

Después de 6 intentos sin éxito, el endpoint se marca como failing y recibirás un email. Tras 7 días seguidos en failing se desactiva automáticamente.

Responde con 200 antes de procesar. Encola el trabajo y ejecútalo de forma asíncrona. Si procesas en línea y tu base de datos tarda, te quedarás sin tiempo y dispararemos reintentos innecesarios.

Siguientes pasos