Callbacks

Handle status of message for each request

Our server can send you notifications any time an event happens with each your lookup request.

To start receiving callbacks/webhook events, you need to pass the set up webhook URL in the dashboard.

Our backend will send POST requests to your server with the JSON body. Your server should return a 200 status code. Any other status code will be considered a failed webhook delivery. Our service will retry a webhook later (up to 30 times) with an increasing delay until you return a response with a status code 200. The first 10 retries are every 30 seconds, the next 10 retries are every 3 mins, and the last 10 retries are every 15 mins. After 30 retries, we will stop sending notifications.

If you're receiving a callback/webhook, it's important to respond as quickly as possible so you don't accidentally run over a timeout limit - 15 seconds. We recommend that your apps defer processing until after the response has been sent. It means returning a response with status code 200 and only then starting to process a JSON that the service sent to you.

If, for some reason, a webhook is retried, it will contain the same ID as in the first attempt. You can use webhook_id as a unique identifier to avoid cases of double processing of each result.

Response format

These are some representative samples of JSON you might receive from our backend. Keep in mind that the response can include additional fields to what's shown here.

With phone details

{
  "contact": "[phone]",
  "request_id": "2f31A2B6-Fd5F-4118-A85f-DafbBcB7f4C2",
  "webhook_id": "32c127be-54a5-4f9a-bf53-2f91c2290e07",
  "result_v1": {
    "apple_services": {
      "facetime": {
        "status": "available",
        "date": "2022-12-13",
        "links": {
          "facetime_audio": "facetime-audio://[phone]",
          "facetime": "facetime://[phone]",
          "tel": "tel://[phone]"
        }
      },
      "imessage": {
        "status": "available",
        "date": "2022-12-12",
        "links": {
          "imessage": "imessage://[phone]",
          "sms": "sms://[phone]"
        }
      }
    },
    "carrier": {
      "carrier": "Verizon",
      "number_type": "mobile"
    },
    "country": {
      "flag": "🇺🇸",
      "iso2": "US",
      "iso3": "USA",
      "name": "United States of America",
      "description": "CA",
      "numeric": 840
    },
    "currencies": [
      "USD", "EUR", "GBP"
    ],
    "format": {
      "e164": "[phone]",
      "international": "[phone]",
      "national": "[phone]",
      "out_of_usa": "1 [phone]",
      "rfc3966": "tel:[phone]"
    },
    "time_zones": [
      "America/Los_Angeles"
    ]
  }
}

Without phone details

{
  "contact": "[phone]",
  "request_id": "2f31A2B6-Fd5F-4118-A85f-DafbBcB7f4C2",
  "webhook_id": "32c127be-54a5-4f9a-bf53-2f91c2290e07",
  "result_v1": {
    "apple_services": {
      "facetime": {
        "status": "available",
        "date": "2022-12-13",
        "links": {
          "facetime_audio": "facetime-audio://[phone]",
          "facetime": "facetime://[phone]",
          "tel": "tel://[phone]"
        }
      },
      "imessage": {
        "status": "available",
        "date": "2022-12-12",
        "links": {
          "imessage": "imessage://[phone]",
          "sms": "sms://[phone]"
        }
      }
    }
  }
}

Possible JSON fields in webhooks

Field	Type	Description
request_id	String	Unique identifier of your request.
webhook_id	String	Unique identifier of the event.
contact	String	Phone number will be converted to the next format: [phone], without spaces and brackets. Email will be converted in lowercase format.
result_v1	Object	Object with lookup result.

Result object

facetime

Field	Type
status	String	Possible values: available, unavailable, unknown.
date	String	Last known date of this data. This can show you how up-to-date this data is. Format of the date: 2023-12-31 The value may be null if the status is not available.
links	Object	{ "facetime_audio": "facetime-audio://[phone]", "facetime": "facetime://[phone]", "tel": "tel://[phone]" } Deep links that can be used to immediately initiate a call with this contact.

imessage

Field	Type
status	String	Possible values: available, unknown.
date	String	Last known date of this data. This can show you how up-to-date this data is. Format of the date: 2023-12-31 The value may be null if the status is not available.
links	Object	{ "imessage": "imessage://[phone]", "sms": "sms://[phone]" } Deep links that can be used to immediately open a chat with this contact.

Phone number details

Any fields in this part of the response is optional

"carrier": {
  "carrier": "Verizon",
  "number_type": "mobile"
},
"country": {
  "flag": "🇺🇸",
  "iso2": "US",
  "iso3": "USA",
  "name": "United States of America",
  "description": "CA",
  "numeric": 840
},
"currencies": [
  "USD", "EUR", "GBP"
],
"format": {
  "e164": "[phone]",
  "international": "[phone]",
  "national": "[phone]",
  "out_of_usa": "1 [phone]",
  "rfc3966": "tel:[phone]"
},
"time_zones": [
  "America/Los_Angeles"
]

Some of the fields, such as carrier, timezone, or currencies, are NOT data that was returned by the contact carrier. You should look at these values ​​as approximated based on the phone number area or country code. Also, in some countries (for example, in the USA), it's not possible to detect a carrier based on the patterns described above.

Headers

These headers will be included in any webhook POST request.

Key	Value
Content-Type	application/json
User-Agent	LoopServer
Connection	close

Best Practices

Authorization

You can configure the authorization header used for webhook requests via the dashboard. Your server should verify the validity of the authorization header for every event. This will help you make sure that a webhook was sent from our service.

IP Whitelisting

Right now, the webhook IP range is variable so we don't recommend hardcode IP of our server. To authenticate requests you can add an authorization token to the webhook that you can then verify on your server.

Response Duration

If your server doesn't finish the response within 15-20s, our backend will disconnect. We then retry up to 30 times. We recommend that apps respond quickly and defer processing until after the response has been sent.

If you use services like ngrok, to prevent abuse, the timeout for webhooks will be around 5 seconds.

Future-Proofing

You should be able to handle webhooks that include all important fields to what's shown here, including new event types. We may add new fields or event types in the future without changing the API version. We won't remove fields or events without proper API versioning and deprecation.