Number Insight webhooks

When an asynchronous Number Insight job resolves, Hablame notifies you with a webhook: you react to the result without polling. This page documents the events the service emits and how to process them.

3 min read

The general webhook contract (signature, headers, retries, security) lives in Webhooks. This page covers only what is specific to Number Insight.

Event catalog

Type	Service	When it fires
`numberinsight.batch.completed`	Number Insight	A batch job finished successfully.
`numberinsight.batch.failed`	Number Insight	A batch job failed definitively.

The numberinsight.batch.completed event

When an asynchronous batch lookup job finishes successfully, this event arrives: use it to trigger the download of the resulting NDJSON without polling.

event payload

{
  "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"
  }
}

The temporary download URL does not travel in the event: its lifetime differs from the webhook signature lifetime. Call GET /api/v6/numberinsight/batch/{jobId} to get a valid download URL.

The NDJSON file

The downloaded file is NDJSON: one JSON line per number.

numbers-out.ndjson

{"input":"3001234567","result":{"phoneNumber":{},"valid":true,"country":{}}}
{"input":"6017430000","result":{"phoneNumber":{},"valid":true,"country":{}}}
{"input":"+5491123456789","result":{"phoneNumber":{},"valid":true,"country":{}}}

Each line has input (what you sent, untouched and in the original order) and result (the same object the single lookup returns).

The numberinsight.batch.failed event

If the job cannot be completed, this event arrives instead of the previous one. The data field carries the jobId and an error with the cause.

event payload

{
  "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"
  }
}