Integrate Webhooks

Get notified about updates

A webhook is an HTTP request used to provide notifications to your System when changes happen in Dotfile.
Dotfile sends webhooks to your server to notify programmatically about:

  • Changes in case status
  • Check lifecycle
    • Check created
    • Check review needed
    • Check completed

Configuring webhooks

To receive webhooks, set up a dedicated endpoint on your server and then set up webhook in Dotfile using our API. Dotfile sends POST requests with a raw JSON payload to your designated endpoint.

To create a webhook using the API, use the Create a new webhook operation

Events

  • Case.StatusUpdated: When case status is updated from one status to another one. Example: case open → approved
  • Check.Started: When a check is started on an entity.
    Example: Start an AML Check on Individual.
  • Check.ReviewNeeded: When a check needs manual review.
    Example: Found hits on AML Check, a reviewer needs to look at the hits.
  • Check.Completed: When a check is completed.
    Example: Ignore all hits (false-positive), The reviewer approves the AML Check, the check is completed (result=approved).

Payload

Payload structure:

{
  "event": "ENTITY_NAME.ACTION_NAME",
  "context": { ... },
  "ENTITY_NAME": { ... }
}

The context depends on the entity:

  • Case: contains the workspace object with its id and name
  • Check: contains:
    • the workspace object with its id and name
    • the case object with its id, external_id, name and status

The context can be useful to verify that the webhook comes from a specific workspace or build URL to the Dotfile App.

You can see all payload definition documented in the Callback section (latest section).

How to test webhook

When integrating a webhook, you need to provide the URL that will be called.

To quickly inspect the payload, you can use webhook.site. It will generate a unique URL and you will see the incoming HTTP Request in your browser.

To start handling webhook locally, you can use ngrok. It will generate a unique URL to expose your local machine to the internet. You can create a webhook with this URL and the incoming request will be forwarded to your machine.

> ngrok http http://localhost:4000/
# will generate an URL like https://0ebb-92-8-30-12.eu.ngrok.io

Sample payload

{
  "event": "Case.StatusUpdated",
  "context": {
    "workspace": {
      "id": "7797fc3e-2bf4-475f-b947-a87a335cf287",
      "name": "Demo"
    }
  },
  "case": {
    "id": "2038b478-1e9d-4b43-ac84-619c2d41a0a4",
    "name": "Dotfile",
    "status": "approved",
    "external_id": "exteid-3",
    "template_id" :"3cad8740-1880-4af8-87f5-25f40ad52951",
    "metadata": {
      "custom_key": "true",
      "my_data": "this is important",
      "count": "42",
    },
    "tags": ["High risk", "Medium risk", "Low risk"],
    "individuals": [
      {
        "id": "21c4d0c9-48dc-4a0a-b92a-3d2db404f703",
        "case_id": "2038b478-1e9d-4b43-ac84-619c2d41a0a4",
        "roles": ["beneficial_owner"],
        "first_name": "John",
        "last_name": "CARTER",
        "email": null,
        "birth_date": "1990-07-03",
        "birth_country": "FR",
        "residence_country": "FR",
        "ownership_percentage": 33.33,
        "created_at": "2022-12-09T16:27:44.255Z",
        "updated_at": "2022-12-09T16:27:44.255Z"
      }
    ],
    "companies": [
      {
        "id": "6b3bfe24-c5d9-4be6-bce6-f6f443cc059e",
        "case_id": "2038b478-1e9d-4b43-ac84-619c2d41a0a4",
        "name": "Test Inc.",
        "registration_number": "012345678",
        "registration_date": "2022-12-06",
        "status": "live",
        "legal_form": "sas",
        "country": "FR",
        "address": {
          "street_address": "11 Rue Poissonnerie",
          "street_address_2": "Apartment 5",
          "postal_code": "64100",
          "city": "Bayonne",
          "region": "Pyrénées-Atlantiques",
          "country": "FR"
        },
        "classifications": [
          {
            "type": "nace",
            "code": "123",
            "description": "very busy"
          }
        ],
        "created_at": "2022-12-09T16:27:37.663Z",
        "updated_at": "2022-12-09T16:27:37.663Z"
      }
    ],
    "created_at": "2022-12-09T16:27:23.968Z",
    "updated_at": "2022-12-12T10:02:12.972Z"
  }
}