Skip to main content

Webhooks

Webhooks allow you to subscribe to real-time events from Konver. When an event occurs, Konver will send an HTTP POST request to the URL you configured.

Managing Webhooks​

You can manage your webhooks in the Developer section of your Organization settings.

Creating a Webhook​

  1. Navigate to Organization > Developer > Webhooks.
  2. Click the Add Webhook button.
  3. Enter the Payload URL where you want to receive the events.
  4. Select the Events you want to subscribe to.
  5. Click Create.

Once created, you will be shown a Webhook Secret. Store this secret securely, as it is used to verify the authenticity of the requests.

Verifying Signatures​

Konver signs the webhook events so you can verify that the request actually came from us. The signature is included in the X-Konver-Signature header.

To verify the signature:

  1. Take the raw request body.
  2. Compute the HMAC-SHA256 of the body using your Webhook Secret.
  3. Compare the computed hash with the value in the X-Konver-Signature header.

Viewing Deliveries​

You can view the history of webhook deliveries to debug issues.

  1. Find the webhook in the list.
  2. Click the Activity icon (pulse icon).
  3. You will see a list of recent deliveries, including the status code, request headers, request body, and response body.

Revoking a Webhook​

If you no longer need a webhook, you can revoke it.

  1. Find the webhook in the list.
  2. Click the Revoke icon (trash icon).
  3. Confirm the action.

Supported Events​

When creating a webhook, you can select from the following event types:

  • call_list.created
  • call_list.updated
  • call_list.deleted
  • call_list_entry.changed
  • company.created
  • company.updated
  • person.created
  • person.updated

Event Structure​

All webhook events follow the same structure:

The data.entity object maps to the API schemas:

{
  "id": "unique-event-id-uuid",
  "eventType": "entity.action",
  "timestamp": "2026-02-04T09:31:19.704044Z",
  "data": {
    "id": "entity-id",
    "entity": {
      // Entity object matching the schema
    }
  }
}

Event Examples​

Call List Created​

{
  "id": "019c27fd-ee0a-78eb-ba2b-c8be29a185b1",
  "eventType": "call_list.created",
  "timestamp": "2026-02-04T09:31:19.704044Z",
  "data": {
    "id": "019c27fd-edfb-7717-ae6c-99f8517355f8",
    "entity": {
      "id": "019c27fd-edfb-7717-ae6c-99f8517355f8",
      "name": "Webhook List",
      "createdAt": "2026-02-04T09:31:18.907562Z",
      "isLocked": false
    }
  }
}

Call List Updated​

{
  "id": "019c2802-1173-743a-9082-6e39fce200c7",
  "eventType": "call_list.updated",
  "timestamp": "2026-02-04T09:35:50.202643Z",
  "data": {
    "id": "019c27fd-edfb-7717-ae6c-99f8517355f8",
    "entity": {
      "id": "019c27fd-edfb-7717-ae6c-99f8517355f8",
      "name": "Webhook",
      "createdAt": "2026-02-04T09:31:18.907562Z",
      "isLocked": false
    }
  }
}

Call List Deleted​

{
  "id": "019c2802-e57b-7d62-b3da-74219b9e07b4",
  "eventType": "call_list.deleted",
  "timestamp": "2026-02-04T09:36:44.500112Z",
  "data": {
    "id": "019c27fd-edfb-7717-ae6c-99f8517355f8",
    "entity": null
  }
}

Call List Entry Changed​

{
  "id": "019c284d-5898-761e-a7b5-f84bd19a35d0",
  "eventType": "call_list_entry.changed",
  "timestamp": "2026-02-04T10:58:04.550029Z",
  "data": {
    "listId": "00000000-0000-0000-0000-000000000000"
  }
}

Company Created​

{
  "id": "019c280f-e1ed-70b4-8140-963ca9861b1b",
  "eventType": "company.created",
  "timestamp": "2026-02-04T09:51:00.667992Z",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "entity": {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "0001-01-01T00:00:00",
      "name": "Test",
      "industry": "Software",
      "website": "https://test.example",
      "email": "contact@test.example",
      "linkedIn": "https://www.linkedin.com/company/test",
      "xing": "https://www.xing.com/pages/test",
      "logoUrl": null,
      "externalId": "ext-12345",
      "externalUrl": "https://external.example/companies/ext-12345",
      "externalOrigin": "crm",
      "phones": []
    }
  }
}

Company Updated​

{
  "id": "019c280f-e1ed-70b4-8140-963ca9861b1b",
  "eventType": "company.updated",
  "timestamp": "2026-02-04T09:51:00.667992Z",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "entity": {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdAt": "0001-01-01T00:00:00",
      "name": "Test",
      "industry": "Software",
      "website": "https://test.example",
      "email": "contact@test.example",
      "linkedIn": "https://www.linkedin.com/company/test",
      "xing": "https://www.xing.com/pages/test",
      "logoUrl": null,
      "externalId": "ext-12345",
      "externalUrl": "https://external.example/companies/ext-12345",
      "externalOrigin": "crm",
      "phones": []
    }
  }
}

Person Created​

{
  "id": "019c2819-ebe2-7f9d-a494-691e63c3f534",
  "eventType": "person.created",
  "timestamp": "2026-02-04T10:01:54.338473Z",
  "data": {
    "id": "019c2819-9bd6-76ca-8498-d427cc9ceb9b",
    "entity": {
      "id": "019c2819-9bd6-76ca-8498-d427cc9ceb9b",
      "createdAt": "2026-02-04T10:01:32.886372Z",
      "companyId": "019c27ef-e61f-74ad-9888-ebbd8eb0983a",
      "name": "John Doe",
      "position": "Co-Founder & CEO",
      "email": "john.doe@example.com",
      "linkedIn": "https://www.linkedin.com/in/john-doe",
      "xing": "https://www.xing.com/profile/John_Doe",
      "logoUrl": "https://example.com/avatars/john-doe.jpg",
      "externalId": "person-98765",
      "externalUrl": "https://external.example/people/person-98765",
      "externalOrigin": "crm",
      "phones": [
        {
          "origin": "Surfe",
          "phone": "+494915734630219"
        }
      ]
    }
  }
}

Person Updated​

{
  "id": "019c2819-ebe2-7f9d-a494-691e63c3f534",
  "eventType": "person.updated",
  "timestamp": "2026-02-04T10:01:54.338473Z",
  "data": {
    "id": "019c2819-9bd6-76ca-8498-d427cc9ceb9b",
    "entity": {
      "id": "019c2819-9bd6-76ca-8498-d427cc9ceb9b",
      "createdAt": "2026-02-04T10:01:32.886372Z",
      "companyId": "019c27ef-e61f-74ad-9888-ebbd8eb0983a",
      "name": "John Doe",
      "position": "Co-Founder & CEO",
      "email": "john.doe@example.com",
      "linkedIn": "https://www.linkedin.com/in/john-doe",
      "xing": "https://www.xing.com/profile/John_Doe",
      "logoUrl": "https://example.com/avatars/john-doe.jpg",
      "externalId": "person-98765",
      "externalUrl": "https://external.example/people/person-98765",
      "externalOrigin": "crm",
      "phones": [
        {
          "origin": "Surfe",
          "phone": "+494915734630219"
        }
      ]
    }
  }
}