Skip to main content

Get notified with webhooks

Webhooks are a standard callback method for web applications. When certain events happen, INFast API sends HTTP request to your server in order to notify you. To do so, you have to provide INFast API with an endpoint on your server.

If the concept of webhooks is new to you, we recommend reading this.

Webhook events​

A detailed list of all the webhook events can be found here.

Request format​

The format of our Webhooks is also standardized. Each call will arrive in the following format:

  • id: a unique identifier for each request
  • portalId: the identifier of the concerned Portal
  • event: contains the details of the sent event
    • eventId: the identifier of the specific Webhook list available here
    • data: the business payload. It is described in detail for each Webhook here
Webhook content example (customer.deleted)
{
  "id": "63e3c82675de4f6978054579",
  "portalId": "63e3c82675de4f6978054555",
  "event": {
    "eventId": "customer.deleted",
    "data": {
      "customerId": "63e3c82675de4f6978054579"
    }
  }
}

Configure webhooks​

Using INFast App​

You can configure your webhook endpoints in the API module of INFast App (Paramètres > Gestion des données > API).

You can have multiple endpoints for the same events if necessary.

INFast App Screenshot

Set up your endpoint​

You have to set the following properties:

  • The url of the endpoints
  • An optional description
  • One or many events to listen to

Test your endpoint​

You can test your endpoint by clicking the "Tester" button.

INFast App Screenshot

Using INFast API​

Dedicated routes are available to subscribe, unsubscribe ans list webhook subscriptions.

Retry strategy​

If your server doesn't respond to the webhook request with a HTTP 200 status, INFast API retries sending the request to your server with the following intervals:

  • 1 second
  • 30 seconds
  • 5 minutes
  • 15 minutes
  • 30 minutes
  • 1 hour
  • 6 hours
  • 12 hours
  • 24 hours

Webhook automatically disabled on multiple fails​

After 100 failures, your webhook endpoint is automatically disabled. An email is sent to you every 10 failures and when the webhook endpoint is disabled.

Test webhooks​

During development, it can be useful to test webhook request reception on your local machine. To do so, you have to use a service redirecting all requests to your local machine, such as ngrok or any other similar solution.

Using ngrok​

  1. Download ngrok
  2. Launch ngrok from command line: ./ngrok http {{your server port}}
  3. Copy the generated HTTPS URL
  4. Use this URL as the endpoint in your webhook configuration

INFast App Screenshot

Verify webhook legitimacy​

All requests are signed with a x-webhook-signature HTTP header. You should verify this signature to ensure the request is coming from INFast API.

Node.js​

You can use the following code to verify signatures:

// Time to live of the signature (in ms).
// It can be more according to the webhook retry strategy.
const SIGN_TIMEOUT = 5 * 60 * 1000;

const verifySignature = function (endpoint, webhook, clientSecret, signature) {
  if (!webhook || !clientSecret || !clientSecret || !signature) {
    return false;
  }

  const match = /v=(\d+),d=([\da-f]+)/.exec(signature);

  if (!match) {
    return false;
  }

  const postStamp = Number(match[1]);
  const postDigest = match[2];
  const timestamp = Date.now();

  if (Math.abs(timestamp - postStamp) > SIGN_TIMEOUT) {
    return false;
  }

  const hmac = crypto.createHmac('SHA256', clientSecret);

  let webhookType = '';
  let webhookData = '';
  if (webhook.event) {
    if (webhook.event.type) {
      webhookType = webhook.event.type.toLowerCase();
    }
    if (webhook.event.data) {
      webhookData = JSON.stringify(webhook.event.data);
    }
  }

  hmac.update(`${endpoint}${webhook._id.toString()}${webhookType}${webhookData}`);

  return hmac.digest('hex') === postDigest;
};