Using Webhooks

Why use Webhooks?

Webhooks are a powerful resource that you can use to automate your workflow and improve the scalability of your implementation.

With the exception of the step where you Create a Business via the API, the Middesk workflow is largely asynchronous.

Since Business entities are not static, it is common for Middesk to find updated information about that Business as it continues to monitor it. If you have a Webhook set up, Middesk can immediately notify you of that change upon discovery.

Some examples of when Middesk would send a Webhook are:

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

Creating a Webhook

If you provide Middesk a Webhook URL, we will send requests to it to notify you any time an event takes place for a Business.

📘
Registering Webhooks
To register your Webhook URL with Middesk, use our Webhooks API or go to the Webhooks section in your Dashboard Settings.

Webhook Events

A Webhook request consists of an Event object payload that Middesk will send via an HTTP POST request to your URL endpoint.

The request contains all the relevant information about how the Business object in question was updated, including the type of event and the data associated with it.

An Event object payload contains the following fields:

Property	Type	Description
object	`string`	value is `event`.
id	`string`	The Middesk defined id representing the event.
created_at	`string`	The timestamp the event was created.
type	`string`	Corresponds to an event, eg `business.created`, `business.updated`.
data	`string`	A container for the data associated with the notification.

{
  "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"
}

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

Types of Webhook Events

Today, Webhook requests consist of the following types:

Type	Description
`business.created`	A new Business has been created.
`business.updated`	The status of a Business has changed (with the exception of when a Business goes into an `in_audit` status).
`industry_classification.created`	A True Industry Classification has been created.
`industry_classification.completed`	A True Industry Classification has completed.
`subscription.created`	A Subscription has been created for a Business.
`subscription.updated`	A Subscription has been updated for a Business.
`tin.retried`	The TIN has been retried successfully.
`agent_tax_registration.created`	The Agent Tax Registration has been created.
`agent_tax_registration.updated`	The status of an Agent Tax Registration has changed.
`lien.updated`	The status of a Lien has changed to `filed` when Middesk files with the state, or to `open` when Middesk has reflected the Lien.

Subscription-specific Webhook Events

If you create a Subscription for a specific event_type, you will receive one or more of the following webhook requests.

Type	Description
`tin.retrieved`	A TIN previously with `unknown: true` has been retried.
`address.created`	A new address was created for the Business.
`address.deleted`	A previously found address was deleted for the Business.
`bankruptcy.created`	A new Bankruptcy has been added to the subscribed Business.
`name.created`	A new name was created for the Business.
`name.deleted`	A previously found name was deleted for the Business.
`person.created`	A new officer was found for the Business.
`person.deleted`	A previously found officer was deleted for the Business.
`registration.created`	A new SOS Registration was created for the Business.
`registration.updated`	A change has been detected for an SOS Registration associated with this Business.

Checking Webhook Signatures

Middesk can optionally sign the Webhook requests that it sends to your endpoints. We do so by including a signature in the request's X-Middesk-Signature header. This header allows you to verify that the requests 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 by Middesk using a hash-based message authentication code (HMAC) with SHA-1. To check the signature, follow these 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 extracted from the header to the expected signature that you computed.

require 'openssl'

secret = 'sec_...'

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

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

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

  status 200
end

from flask import Flask, request, abort
import hmac
import hashlib
import json
app = Flask(__name__)


secret = 'sec_...'


def verify(payload, signature):
    expected = hmac.new(secret, payload, hashlib.sha1).hexdigest()
    return expected == signature


@app.route('/my/webhook/url', methods=['POST'])
def receive_webhook():
    payload = request.data
    sig_header = request.headers['X-Middesk-Signature']

    if not verify(payload, sig_header):
        # Invalid signature
        abort(400)

    event = json.loads(payload)

    if event['type'] == 'business.created':
        business = event['data']['object']
        print('Business created!')
    elif event['type'] == 'business.updated':
        business = event['data']['object']
        print('Business updated!')
    # ... handle other event types
    else:
        # Unexpected event type
        abort(400)

    return ''

IP Addresses for Webhooks

Below is the list of IP addresses that Middesk sends webhook requests from:

35.239.59.102
35.192.63.74
104.198.38.1

Why use Webhooks?

Creating a Webhook

📘Registering Webhooks

Webhook Events

🚧

Types of Webhook Events

Subscription-specific Webhook Events

Checking Webhook Signatures

Step 1: Extract the signature from the header

Step 2: Prepare the expected signature

Step 3: Compare the Signatures

IP Addresses for Webhooks

📘
Registering Webhooks