Webhooks (disparadores)

RankLadder envía eventos a tus sistemas con un modelo REST Hooks: suscribes una URL a un tipo de evento, y RankLadder hace un POST con un payload JSON a esa URL cada vez que el evento ocurre. Es el mismo mecanismo que usan por debajo las apps de Zapier y Make.

Todos los endpoints requieren autenticación.

Suscribirse

POST /api/v1/hooks

Cuerpo:

{
  "event": "new_conversation",
  "target_url": "https://example.com/rankladder-hook"
}

target_url debe ser HTTPS. Respuesta:

{ "id": "d4e5f6a7-0000-4000-8000-000000000000" }

Guarda el id si quieres cancelar la suscripción más adelante.

Ejemplo:

curl -X POST https://app.rankladder.app/api/v1/hooks \
  -H "Authorization: Bearer rl_zapier_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "missed_call", "target_url": "https://example.com/rankladder-hook"}'

Errores: un tipo de evento desconocido devuelve 400 con { "error": "invalid_event" }; una URL ausente, inválida o sin HTTPS devuelve 400 con { "error": "invalid_target_url" }.

Listar suscripciones

GET /api/v1/hooks

Respuesta:

{
  "hooks": [
    {
      "id": "d4e5f6a7-0000-4000-8000-000000000000",
      "event_type": "missed_call",
      "target_url": "https://example.com/rankladder-hook",
      "created_at": "2026-08-05T12:00:00Z"
    }
  ]
}

Cancelar una suscripción

DELETE /api/v1/hooks/{id}

Respuesta: { "ok": true }.

Revocar tu clave de API también elimina todas las suscripciones creadas con ella.

Entrega

RankLadder envía un POST a cada URL suscrita con Content-Type: application/json:

{
  "event": "missed_call",
  "data": { "...": "campos del evento, ver abajo" }
}

La entrega es como máximo una vez. Si tu endpoint está caído o devuelve un error, esa entrega no se reintenta.

Tipos de evento

new_conversation

Se dispara cuando termina una llamada telefónica, tanto si la IA la atendió como si fue al buzón de voz. Se excluyen las llamadas de spam y los cuelgues inmediatos. Por ahora, solo llamadas de voz: las conversaciones de texto y de chat web todavía no disparan este evento.

{
  "event": "new_conversation",
  "data": {
    "conversation_id": "a1b2c3d4-0000-4000-8000-000000000000",
    "channel": "voice",
    "caller_name": "Sam Alvarez",
    "caller_number": "+15035551234",
    "summary": "Caller asked about weekend appointment availability."
  }
}

missed_call

Se dispara cuando la llamada fue al buzón de voz. Tiene los mismos campos que new_conversation. Una llamada al buzón de voz dispara ambos eventos, así que suscríbete solo a uno de los dos si no quieres dos entregas por la misma llamada.

{
  "event": "missed_call",
  "data": {
    "conversation_id": "a1b2c3d4-0000-4000-8000-000000000000",
    "channel": "voice",
    "caller_name": "Sam Alvarez",
    "caller_number": "+15035551234",
    "summary": "Caller left a voicemail about a leaking water heater."
  }
}

new_contact

Se dispara cuando se crea un contacto nuevo en RankLadder, ya sea sincronizado desde un CRM conectado o creado mediante la acción de crear contacto. source es el proveedor que creó el contacto, por ejemplo jobber, square, zapier o make.

{
  "event": "new_contact",
  "data": {
    "contact_id": "b2c3d4e5-0000-4000-8000-000000000000",
    "name": "Sam Alvarez",
    "phone": "+15035551234",
    "source": "jobber"
  }
}