Webhooks

Webhooks are a mechanism that allow you to supply a URL to the FullContact API so that we can send back data once an operation is complete.

For the requests that support them, webhooks are defined in the request body using the webhookUrl field.
For example, the Person Enrichment request allows you to supply a
Multi Field Request, with an additional property for a webhookUrl

When a webhook has been provided for a given request, an HTTP POST request will be sent to the URL provided once the
process has completed. The payload of the POST request will mirror the responses of most other
FullContact API requests, with data sent as JSON within the POST body.

curl -X POST https://api.fullcontact.com/v3/person.enrich \
-H "Authorization: Bearer {Your API Key}" \
-d '{"email":"[email protected]","phone":"+7202227799","webhookUrl":"http://www.fullcontact.com/hook"}'

You may provide multiple custom identifiers that may be useful for linking the initial request to the webhook response by making use of query parameters on the webhookUrl. For example, your webhookUrl could be: http://yourdomain.com/path1/subpath?identifier=12345&segment=prospect. By using query parameters, you are able to provide multiple parameters.

During development and while testing webhooks, we recommend intercepting the webook POST requests locally, or using a web-based webhook testing service. We use ngrok and netcat to simulate catching the webhook.

Testing Webhooks Locally

Example of catching a webhook (CTRL+C to kill)

ngrok http 1337
while true ; do  echo -e "HTTP/1.1 200 OK\n\n $(date)" | nc -l 1337; test $? -gt 128 && break ; done

ngrok by @inconshreveable                                                     (Ctrl+C to quit)

Session Status                online
Version                       2.3.40
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://605e-97-118-10-198.ngrok.io -> http://localhost:1337
Forwarding                    https://605e-97-118-10-198.ngrok.io -> http://localhost:1337

Connections                   ttl     opn     rt1     rt5     p50     p90
                              6       0       0.07    0.02    0.00    0.06

Testing the Enrich API with a webhook from ngrok

curl -X POST https://api.fullcontact.com/v3/person.enrich \
-H "Authorization: Bearer {Your API Key}" \
-d '{"email":"[email protected]", "webhookUrl":"http://605e-97-118-10-198.ngrok.io"}'

{
  "status": 202,
  "message": "Queued for search. Your response will be sent to your webhook shortly at http://605e-97-118-10-198.ngrok.io."
}