Secure webhooks

Middesk supports three approaches to verify that webhook notifications are authentic and originate from Middesk.

Verify signatures

Middesk signs webhook requests by including a signature in the X-Middesk-Signature-256 header. Verify this signature to confirm the request came from Middesk.

Set up signature verification

Before you can verify signatures, define a secret using the Webhooks API.

Middesk generates signatures using HMAC with SHA-256.

Verify the signature in your webhook endpoint

1. Extract the signature from the X-Middesk-Signature-256 header.
2. Compute an HMAC with SHA-256 using your secret as the key and the raw request body as the message.
3. Compare the header signature to your computed signature using a constant-time comparison method.

1
require 'openssl'
2
3
secret = 'sec_...'
4
5
def verify(payload, signature)
6
  digest = OpenSSL::Digest.new('sha256')
7
  expected = OpenSSL::HMAC.hexdigest(digest, secret, payload)
8
  OpenSSL.secure_compare(expected, signature)
9
end
10
11
post '/my/webhook/url' do
12
  payload = request.body.read
13
  sig_header = request.env['X_MIDDESK_SIGNATURE_256']
14
15
  unless verify(payload, sig_header)
16
    # Invalid signature
17
    status 400
18
    return
19
  end
20
21
  event = JSON.parse(payload)
22
23
  case event.type
24
  when 'business.created'
25
    business = event.data.object
26
    puts 'Business created!'
27
  when 'business.updated'
28
    business = event.data.object
29
    puts 'Business updated!'
30
  # ... handle other event types
31
  else
32
    # Unexpected event type
33
    status 400
34
    return
35
  end
36
37
  status 200
38
end

Use Mutual TLS

The second way to authenticate webhook notifications is to verify Middesk’s client certificate during the TLS handshake.

In standard TLS, only the server presents a certificate. With Mutual TLS, the client (Middesk) also presents a certificate. Configure your server to request and verify this client certificate during the TLS handshake.

Verify Middesk’s certificate

Middesk’s webhook client certificate is issued by the DigiCert Assured ID Root G2 Certificate Authority. This CA is configured on most operating systems by default, or you can download it directly.

Verify the client certificate has these Subject Distinguished Name (Subject DN) fields:

O=Middesk\, Inc.
CN=webhooks.middesk.com

These fields confirm the certificate was issued to Middesk, Inc. and is used for the intended purpose.

Configure reverse proxies

If you use a reverse proxy for TLS termination, configure it to request and verify the client certificate before routing requests to your backend. Verify the certificate subject matches the fields above before forwarding the request.

Use OAuth access tokens

A third, but most advanced, mechanism to authenticate webhook notifications is to use OAuth access tokens issued by your OpenID Connect Identity Provider. This method is best for enterprises with complex security requirements.

Use this method if:

• HMAC shared secrets don’t meet your security requirements. Your organization prohibits sharing secrets externally.
• Mutual TLS is incompatible with your infrastructure. Your edge proxies don’t support client certificate authentication or make it difficult to relay certificate information to backend applications.
• You need separation of security responsibilities. Security teams manage the Identity Provider while application teams focus on token verification.
• You require precise token scoping. Tokens can be scoped to specific resource URIs.
• You must comply with internal governance. Your organization requires internal IdP-issued tokens for all integrations.

How OAuth authentication works

Refer to your internal documentation for token validation specifics.

Set up OAuth authentication

Configure webhooks to use OAuth

After completing the setup, configure your webhook to use OAuth access tokens via the API. Include these four fields when creating or updating a webhook (currently not available in the Webhooks UI):