Using Webhooks

Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity.

Unlike the API resources, which represent static data that you can create, update, and retrieve as needed, webhooks represent dynamic resources. Webhooks are especially useful for events that are not triggered by a direct API request, such as when Business details are updated.

Why use webhooks?

Webhooks are useful to keep up-to-date with the progress of a Business.

Some requests (e.g., Creating a business) generate results that are reported synchronously and may not require webhooks.

Since not all processes allow for synchronous responses, webhooks will allow your integration to be notified on changes to the status of a Business as soon as they are available. Here are some examples where webhooks are commonly employed:

  • Approving a new account when a Business is complete and meets requirements
  • Notifying a team when a Business requires further review
  • Updating account profiles with accurate, validated business information

Using webhooks

If you provide a webhook URL, we will use it to notify you any time an event takes place for a Business. When the event occurs, Middesk creates an Event object and attempts to publish this to your webhook URL.


Getting started with webhooks

To register your webhook URL with Middesk, use our Webhooks API or contact [email protected] for assistance.

This Event object contains all the relevant information about what just happened to the Business object in question, including the type of event and the data associated with that event type.

Middesk sends the Event object via an HTTP POST request to your URL endpoint.

Checking webhook signatures

Middesk can optionally sign the webhook events it sends to your endpoints. We do so by including a signature in each event’s X-Middesk-Signature header. This allows you to verify that the events were sent by Middesk, not by a third party.

Before you can verify signatures, you'll need to set a secret via the Webhooks API.

Signatures are generated using a hash-based message authentication code (HMAC) with SHA-1. To so, follow the below steps:

Step 1: Extract the signature from the header

Read the value from the X-Middesk-Signature header.

Step 2: Prepare the expected signature

Compute an HMAC with the SHA-1 hash function. Use the provided secret as the key, and use the response body as the message.

Step 3: Compare the signatures

Compare the signature in the header to the expected signature.

require 'openssl'

secret = 'sec_...'

def verify(payload, signature)
  digest ='sha1')
  expected = OpenSSL::HMAC.hexdigest(digest, secret, payload)
  expected == signature

post '/my/webhook/url' do
  payload =
  sig_header = request.env['X_MIDDESK_SIGNATURE']

  unless verify(payload, sig_header)
    # Invalid signature
    status 400
  event = JSON.parse(payload)
  case event.type
  when 'business.created'
    business =
    puts 'Business created!'
  when 'business.updated'
    business =
    puts 'Business updated!'
  # ... handle other event types
    # Unexpected event type
    status 400

  status 200


Middesk today supports the following Event types. Your registered webhook URL can be notified when that Event occurs on your account. The Subscription Available column indicates whether or not you can create a Subscription for that type (see Subscription Overview).

TypeDescriptionSubscription Available
business.createdA new Business has been created.No
business.updatedThe status of a Business has changed.No
industry_classification.createdA True Industry Classification has been created.No
industry_classification.completedA True Industry Classification has completed.No
watchlist_result.createdA Watchlist Result has been identified for a Business.Yes
bankruptcy.createdA Bankruptcy has been identified for a Business.Yes
subscription.createdA Subscription has been created for a Business.No
subscription.updatedA Subscription has been updated for a Business.No
tin.retriedThe TIN has been retried successfully.No
agent_tax_registration.createdThe Agent Tax Registration has been created.No
agent_tax_registration.updatedThe status of an Agent Tax Registration has changed.No

Middesk will add new events in the future. If there are specific events that you would like prioritized, please contact [email protected].

Event payloads

An Event payload contains the following fields:

objectstringvalue is event.
idstringThe Middesk defined id representing the event.
created_atstringThe timestamp the event was created.
typestringCorresponds to an event, eg business.created, business.updated.
dataobjectA container for the data associated with the notification.

Example delivery

  "object": "event",
  "id": "f215a707-655e-400f-84e6-fbb949f5612a",
  "type": "business.created",
  "data": {
    "object": {
      "id": "0f86dab5-8195-4b95-b3c0-19deaeba2a8e",
      "tin": null,
      "name": "A Company",
      "tags": [],
      "names": [],
      "domain": null,
      "object": "business",
      "review": null,
      "status": "open",
      "orders": [
          "id": "d9e4076c-25d7-4a93-917b-66568459cbc4",
          "object": "order",
          "status": "pending",
          "product": "identity",
          "created_at": "2020-01-02T23:54:48.180Z",
          "updated_at": "2020-01-02T23:54:48.180Z",
          "completed_at": null
      "summary": null,
      "website": null,
      "officers": [],
      "addresses": [],
      "formation": null,
      "watchlist": null,
      "created_at": "2020-01-02T23:54:48.154Z",
      "updated_at": "2020-01-02T23:54:48.154Z",
      "external_id": null,
      "phone_numbers": [],
      "registrations": []
  "created_at": "2020-01-02T23:54:48.239Z"

Middesk IP Addresses for Webhooks

Below is a full list of IP Addresses that Middesk uses to emit Webhooks:


We're always happy to help with code or other questions you might have! Feel free to reach out to [email protected].

What’s Next

Dig deeper into Middesk's available endpoints and resources.