Number Insight webhook

When an asynchronous Number Insight job resolves, Hablame notifies you with a webhook, so you can react to the outcome without polling. This page documents the events the service emits and how to process them; you'll find them all in the event catalog. The general webhook contract (signing, headers, retries) lives in Generalities.

Event catalog

typeServiceWhen
numberinsight.batch.completedNumber InsightA batch job finished successfully.
numberinsight.batch.failedNumber InsightA batch job failed permanently.

Event numberinsight.batch.completed

When an asynchronous Number Insight job finishes successfully, this event arrives, useful 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 is not part of the event (its lifetime differs from the webhook signing window). Call GET /api/v6/numberinsight/batch/{jobId} to get a fresh temporary download URL.

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, in original order) and result (same object as the 1:1 lookup).

Event numberinsight.batch.failed

If the job can't be completed, this event arrives instead of completed. The data 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": "could not read the input file"
  }
}