Implement webhooks

Most Middesk operations are asynchronous: for example, business verification continues after the initial API request. Webhooks allow you to receive notifications when important activity occurs, such as:

• Business verification status changes (for example, from pending to in_review)
• New information is discovered through ongoing monitoring
• Order or Monitor updates occur

Without webhooks, you need to poll the API repeatedly to check for changes. Webhooks eliminate this overhead and ensure you never miss important events.

Register a webhook endpoint

To receive webhooks, provide Middesk with a URL endpoint that accepts HTTP POST requests.

You can register webhook URLs in two ways:

• Use the API through the Webhooks API to create and manage endpoints programmatically
• Use the Dashboard under Settings > Webhooks

Note that you must create separate webhook endpoints for sandbox and Production requests.

The webhook endpoint has two requirements:

• It must be a publicly available URL (see the IP lists below to restrict access to only Middesk).
• The endpoint must return a 2xx status code to indicate receipt of the webhook notification.

Webhook payload structure

Middesk sends webhooks as HTTP POST requests with an Event object in the request body.

Each Event object includes:

The X-Correlation-Id header contains the external_id if one was provided, otherwise it contains the primary object ID. This allows easy mapping when only headers are available.

1
{
2
  "object": "event",
3
  "id": "f215a707-655e-400f-84e6-fbb949f5612a",
4
  "type": "business.created",
5
  "data": {
6
    "object": {
7
      "id": "0f86dab5-8195-4b95-b3c0-19deaeba2a8e",
8
      "tin": null,
9
      "name": "A Company",
10
      "tags": [],
11
      "names": [],
12
      "domain": null,
13
      "object": "business",
14
      "review": null,
15
      "status": "open",
16
      "orders": [
17
        {
18
          "id": "d9e4076c-25d7-4a93-917b-66568459cbc4",
19
          "object": "order",
20
          "status": "pending",
21
          "product": "identity",
22
          "created_at": "2020-01-02T23:54:48.180Z",
23
          "updated_at": "2020-01-02T23:54:48.180Z",
24
          "completed_at": null
25
        }
26
      ],
27
      "summary": null,
28
      "website": null,
29
      "officers": [],
30
      "addresses": [],
31
      "formation": null,
32
      "watchlist": null,
33
      "created_at": "2020-01-02T23:54:48.154Z",
34
      "updated_at": "2020-01-02T23:54:48.154Z",
35
      "external_id": null,
36
      "phone_numbers": [],
37
      "registrations": []
38
    }
39
  },
40
  "created_at": "2020-01-02T23:54:48.239Z"
41
}

Event types

Middesk sends webhook notifications for the following event types:

Core events

Monitor events

When you monitor specific event types, Middesk sends webhooks for these events:

Retry behavior

If a webhook delivery fails, Middesk automatically retries up to 10 times over approximately 3 days:

1. Initial delivery attempt.
2. If failed, retry after 1-30 seconds.
3. Subsequent retries use exponential backoff.
4. Final retry occurs ~3 days after the initial attempt.

A delivery is considered successful when your endpoint returns a 2xx HTTP status code.

Webhook IP addresses

Middesk sends webhook requests from these IP addresses:

• 35.239.59.102
• 35.192.63.74
• 104.198.38.1

Use these addresses to configure firewall rules or IP allowlists for your webhook endpoint.

Webhooks and Policies

If Policies is enabled, Middesk doesn’t send business.updated notifications when the business enters the in_review stage. Instead, Middesk sends a business.updated webhook with the relevant result only after evaluating the Policy rules.

The following are the various status values that a Business can have with Policies enabled: