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 ?

First of all you need to access your profile using the dropdown.

Once you are on your profile, you will have to activate your API access.
You have to go to the API section by clicking on API. Now, all you have to do is toggle your API access switch.

Then you can setup your URL 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 ?

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 on the same system as the API itself.
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.