Webhooks y API (Business)

Si tu negocio requiere integración custom con sistemas propios (ERP, CRM custom, marketplace propio), Brote expone webhooks salientes y API REST — disponibles en plan Business ($349/mes).

Webhooks salientes

Cada evento del sistema Brote dispara un POST HTTPS a los endpoints que configures, firmado con HMAC-SHA256.

Eventos disponibles

conversation.created
conversation.updated
conversation.closed
message.received
message.sent
contact.created
contact.updated
contact.opted_out
ticket.created
ticket.stage_changed
ticket.won
ticket.lost
lead.qualified
payment.received
campaign.completed
agent.handoff

Payload típico

{
  "event": "payment.received",
  "timestamp": "2026-05-19T10:23:45.000Z",
  "organization_id": "uuid",
  "data": {
    "payment_id": "mp_payment_123",
    "amount": 49000,
    "currency": "CLP",
    "conversation_id": "uuid",
    "contact_id": "uuid",
    "contact": {
      "name": "María González",
      "phone": "+569·········",
      "email": "maria@ejemplo.cl"
    },
    "external_reference": "ticket_uuid"
  }
}

Verificar HMAC

Header X-Brote-Signature: sha256=<hex>. Computas en tu servidor:

const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex')
const isValid = `sha256=${expected}` === req.headers['x-brote-signature']

Si no validás el HMAC, cualquiera podría postearte fake events. Validá siempre.

Retries + deliveries log

Si tu endpoint responde con 5xx o timeout, Brote re-intenta con backoff exponencial: 1min, 5min, 30min, 2h, 12h. Después marca como failed. Todas las entregas (exitosas y fallidas) quedan en el log de webhook_deliveries consultable desde el dashboard.

API REST

Endpoint base: https://api.brote.ai/v1/

Auth: Bearer token (API key per-org, generás desde Configuración → API Keys).

Endpoints principales

GET    /v1/contacts              # listar contactos
POST   /v1/contacts              # crear contacto
GET    /v1/contacts/{id}         # detalle
PATCH  /v1/contacts/{id}         # actualizar

GET    /v1/conversations         # listar conv
POST   /v1/conversations/{id}/messages   # enviar mensaje desde sistema externo

GET    /v1/tickets               # listar tickets
PATCH  /v1/tickets/{id}/stage    # mover etapa

POST   /v1/payments/links        # crear link MP programático
GET    /v1/payments              # listar pagos

GET    /v1/campaigns             # listar campañas
POST   /v1/campaigns             # crear campaña vía API

Rate limits

100 req/min sostenido en plan Business.
Burst de 200 ocasional.
Si superas: 429 con Retry-After header.