Skip to main content

Enterprise webhooks

  • Updated

MessageMedia webhooks can be further secured so that you are ensured of the source of the payload. This is a two-part process involving, first, creating a public-private key pair and, second, verifying your webhook by making use of those keys. In this guide we will complete both parts of this process:

Prerequisites

Create a pair of keys

The first part of this is to create a pair of keys, a private and a public one. The private key will be used by MessageMedia to sign the webhook and the public one will be used by MessageMedia to verify the signature. Create a signature key using the "Create Signature Key" endpoint. The CURL request for this is: 

curl -X POST \
  --url 'https://api.messagemedia.com/v1/iam/signature_keys' \
  -u '7EVUfEYzkBu69Uf1DHJO:xMpI2vrdtFJeKzrRNiUGpWOAoUgxNn'\
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  --data-raw '{
  "digest": "SHA224",
  "cipher": "RSA"
}'

As you can see, only the public key will be returned in the response: 

{"key_id":"fd0d23bd-36ea-40ab-8d27-55fc3947604d","created":"2020-03-18T01:26:06.099Z","cipher":"RSA","digest":"SHA224","enabled":false,"public_key":"MIIBIjANBgkqhkiG9w0..."}

The private key will be held by MessageMedia in its secure data store. The digest is used to hash the message and the supported values for the digest type are SHA224, SHA256, SHA512. The cipher is used to encrypt the hashed message and the supported value for it is RSA.

Notice how the key is enabled status of the key is set to false? The key now needs to be enabled.

Enable and disable the key

The Signature Key Management API allows you to create multiple pairs of keys, but you can only use one at a time. This is why you need to enable the key that you would like to use. You update the status using the key_id returned in the previous step: 

curl -X PATCH \
  --url 'https://api.messagemedia.com/v1/iam/signature_keys/enabled' \
  -u '7EVUfEYzkBu69Uf1DHJO:xMpI2vrdtFJeKzrRNiUGpWOAoUgxNn'\
  -H 'Accept: application/json' \
  -H 'Content-type: application/json' \
  --data-raw '{
  "key_id": "fd0d23bd-36ea-40ab-8d27-55fc3947604d"
}'

This will return the detail of the key again, but with the enabled field set to "true".

{"key_id":"fd0d23bd-36ea-40ab-8d27-55fc3947604d","created":"2020-03-18T01:26:06.099Z","cipher":"RSA","digest":"SHA224","enabled":true}

You can disable the currently enabled key using a DELETE request to the endpoint above. 

curl -X DELETE \
  --url 'https://api.messagemedia.com/v1/iam/signature_keys/enabled' \
  -u '7EVUfEYzkBu69Uf1DHJO:xMpI2vrdtFJeKzrRNiUGpWOAoUgxNn'

This will result in a null response.

Part 2: 

Once you have enabled a signature key all webhooks sent will be signed using the private key created via the Signature Key Management API and they will come with some additional headers. You can use these headers to verify that the webhook is being sent to you by a known service. 

Doing this will require you to deploy some server side code, so we have create code samples in six languages for this part: 

node.js

python

ruby

c#

java

php

Clone any of these repositories on you local computer and install the dependencies to use them.

Running locally using NGROK

We can run Express on port 3000 and pass in the URL (localhost:3000) as a callback URL but the Messages API doesn't like loopback addresses. We'll need to expose our local server via a public URL which we can then feed to the Messages API and that's where ngrok comes into play. Install ngrok on your local system and then run the following command:

ngrok http 3000

If all goes well you should see the following:

 

One of ngrok has a UI to inspect requests. You can access it by following the Web Interface URL (127.0.0.1:4040) which can be seen in the screen above.

Add public key

In the main application file of the sample code you copied, replace PUBLIC_KEY_HERE with the key you were provided with earlier when you created a key pair via the Signature Key Management API.

Testing with an event

To test your secure webhook, you can send a message with the callback_url set to the address of your ngrok external URL. 

{
  "messages": [
    {
     "content": "Hey there!",
     "destination_number": "+614<phone_number_here>",
     "format": "SMS",
     "delivery_reports": true,
     "callback_url": "http://c8e3b8d9.ngrok.io/hello"
    }
  ]
}

Once you have sent a message, open up the Web Interface and you should see something similar.

In this example, the callback_url is to push delivery reports and replies to the URL specified. Delivery Reports, or DRs, are simply notifications of changes in the status of a message as it is being processed. Whenever a Webhook is triggered, a DR is sent back to the callback_url notifying you of any changes. A Webhook can be triggered by replies as well. 

Conclusion

This guide can be used to create signature keys and use them to verify the authenticity of your Webhooks. In this example, we have used the callback_url which will send you both DRs and replies. However, you can set up custom webhooks, which will also use any enabled signature keys, by using the webhooks management endpoints detailed in the documentation.

Related articles