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 = 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

Events

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).

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:

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:

35.239.59.102
35.192.63.74
104.198.38.1

Questions?

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