Webhooks de Number Insight
Cuando un trabajo asíncrono de Number Insight se resuelve, Hablame te avisa con un webhook: reaccionas al resultado sin consultar en bucle. Esta página documenta los eventos que emite el servicio y cómo procesarlos.
3 min de lectura
El contrato general de webhooks (firma, headers, reintentos, seguridad) está en Webhooks. Esta página cubre solo lo específico de Number Insight.
Catálogo de eventos
| Tipo | Servicio | Cuándo se emite |
|---|---|---|
numberinsight.batch.completed | Number Insight | Un trabajo por lote terminó correctamente. |
numberinsight.batch.failed | Number Insight | Un trabajo por lote falló de forma definitiva. |
Evento numberinsight.batch.completed
Cuando un trabajo asíncrono de consulta por lote termina con éxito, llega este evento: sirve para activar la descarga del NDJSON resultante sin consultar en bucle.
{
"id": "5e3f2a7c-1d8b-4c19-9e6c-8e0f7d5a2c3e",
"type": "numberinsight.batch.completed",
"version": 1,
"service": "numberinsight",
"accountId": 123,
"occurredAt": "2026-06-18T09:14:22+00:00",
"data": {
"jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1",
"count": 12450,
"processed": 12450,
"format": "ndjson"
}
}La URL de descarga temporal no viaja en el evento: su vigencia es distinta de la de la firma del webhook. Llama a GET /api/v6/numberinsight/batch/{jobId} para obtener una URL de descarga vigente.
El archivo NDJSON
El archivo descargado es NDJSON: una línea JSON por número.
{"input":"3001234567","result":{"phoneNumber":{},"valid":true,"country":{}}}
{"input":"6017430000","result":{"phoneNumber":{},"valid":true,"country":{}}}
{"input":"+5491123456789","result":{"phoneNumber":{},"valid":true,"country":{}}}Cada línea tiene input (lo que enviaste, sin tocar y en el orden original) y result (el mismo objeto que devuelve la consulta uno a uno).
Evento numberinsight.batch.failed
Si el trabajo no se puede completar, llega este evento en lugar del anterior. El campo data trae el jobId y un error con la causa.
{
"id": "7a1c9e4d-2b6f-4d3a-8c12-1f0e6d9b4a2c",
"type": "numberinsight.batch.failed",
"version": 1,
"service": "numberinsight",
"accountId": 123,
"occurredAt": "2026-06-18T09:15:03+00:00",
"data": {
"jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1",
"error": "no se pudo leer el archivo de entrada"
}
}