Webhooks

With webhooks, you can easily avoid unnecessary calls to Vainu API and only receive notifications when content gets changed. Webhooks are partially supported through API, with planned full support coming with upcoming releases.

Vainu has support for two types of webhooks. Company data updates are webhooks sent when the basic data of the company is changed. These webhooks are manageable through the API. Triggers are events generated by Vainu. Support for webhooks for triggers is available only from Vainu platform UI.

Company data updates

Company data updates are notifications sent as a webhook to your given endpoint. The Notification payload only includes basic information of the company updated but can be used in series with the Get Companies endpoint to fetch the rest of the necessary data.

Vainu uses Customer data objects to evaluate which companies will be tracked. So for a webhook to function, it's necessary to create a list of companies with Customer data endpoints of Vainu API. After this step, the webhook can be configured from the API.

{
  "data": {
    "status": "active",
    "domain": "vainu.com",
    "turn_over": 895766,
    "visiting_address": "Etel\u00e4esplanadi 12",
    "business_id": "25578642",
    "company_name": "Vainu. io Software Oy",
    "visiting_city": "HELSINKI",
    "visiting_postal": "00130",
    "staff_number": 12,
    "region": "FI-18"
  },
  "number_of_tries": 1,
  "type": "company_change_webhook",
  "unique_id": "123abc"
}

Configure Webhooks

Webhook configuration, status and removal are available from the Configure Webhooks endpoint. For a single webhook, you can set the URL, query and type. URL will be the target address where webhooks are sent, and the query has optional query parameters for your address.

The only supported type for webhooks is "company_change_webhook". This type indicates changes in company data. Compay change webhook payload will include limited data fields from the company and details of the webhook.

POST https://api.vainu.io/api/v2/webhook_configuration/'

body = {
  "webhook_url": "https://www.example.com/webhook_endpoint",
  "query": "?crm=custom",
  "type": "company_change_webhook"
}

You can get all the configured webhooks by using GET request on the Webhook configuration endpoint. This request will return all configured webhooks and their details.

{
  "results": [
    {
      "webhook_url": "https://www.example.com/webhook_endpoint",
      "query": "?crm=custom",
      "id": "5f5b7b3ebb9378063bc322ef",
      "username": "[email protected]",
      "type": "company_change_webhook"
    }
  ]
}

Webhook id can be used to remove an existing webhook. You can remove webhooks with DELETE request to Webhook configuration endpoint with webhook id set to the path of the request.

Triggers

The Triggers support webhooks as a delivery method. This webhook configuration is only available from the Vainu platform, and webhook delivery addresses with content can be managed from the Vainu platform UI.

Webhook configuration for the data updates can be done from the API.