Setup the push notifications

Icypeas can send notifications to your app if you provide the correct URLs. The different kinds of notifications you can get are:

2. A summary about your results at the end of a bulk search;
3. Updates for each single search or each item in your bulk search;

tip

This is the preferred way to check progress in the API. So please, consider using this system instead of checking progress by querying our API at regular interval.

How do you set the routes ?

1. Go the API section and enable API access (if not done):

2. Setup your URLs for the push notifications:

info

Activating a notification route is simply adding the correct URL in the text input and saving the changes.

How to verify the authenticity of the calls ?

info

This is an optional step, you do not have to do this, if you do not want to.

All routes will be called using a POST request and the body has the following form:

{
  "signature": "HMAC-SHA1 signature",
  "timestamp": "The timestamp to use in the signature's calculation",
  "data": "An object containing the relevent data depending on the notification"
}

The security of our calls is based a signature and a timestamp using your API secret. We use a HMAC-SHA1 signature and a timestamp.
To compute the signature in the object you need to follow this simple procedure:

1. Get the URL to which we sent you the request, for instance: https://example.com/icypeas-notifications/bulksearch-end.
2. Grab the endpoint (the path name): /icypeas-notifications/bulksearch-end
3. Grab the UTC timestamp in the request.
4. Concatenate the endpoint + the timestamp and lowercase your final string.
5. Use the library in your language to create a HMAC-SHA1 signature of this payload using your secret.

Here you'll find the way to do it with NodeJS:

import { URL } from 'URL';
import Crypto from 'crypto';

/**
 * Generate the signature when you receive a request from Icypeas
 * @param url - The api route we sent a request to
 * @param timestamp - The ISO 8601 timestamp sent in the request (ex: 2023-03-01T04:40:20Z)
 * @param secret - Your API secret
 */
const genSignature = (
    url: string,
    timestamp: string
    secret: string,
) => {
    const endpoint = new URL(url).pathname;
    const payload = `${endpoint}${timestamp}`.toLowerCase();
    const sign = Crypto.createHmac("sha1", secret).update(payload).digest("hex");

    return { signature: sign };
};

Now all that's left is to check whether the computed signature is the same that the one we sent.