Developer HubProtocols
API Reference

Forwarding 2.0: Webhook

Forward Messages

🚧

Security Configuration

The device must have the appropriate whitelists configured in order to allow message forwarding.

Meshblu will automatically call a webhook for every message sent to a device with webhook forwarders enabled. Meshblu supports request style options. The body of the HTTP request will contain the message.

Webhook Forwarders Types:

  • broadcast.received: forward broadcast messages received from other devices
  • broadcast.sent: forward broadcast messages sent from the current device
  • configure.received: forward config messages received from other devices
  • configure.sent: forward configure messages sent from the current device
  • message.received: forward messages received from other devices
  • message.sent: forward messages sent by the current device
  • unregister.received: forward the final device state from the current device before deleting
  • unregister.sent: forward the final device state from other devices before deleting 
{
  "meshblu": {
    "forwarders": {
      "version": "2.0.0",
      "message": {
				"sent": [
        	{
      			"type": "webhook",
          	"url": "http://requestb.in/18gkt511",
          	"method": "POST"
        	}
    		]
      }
    }
  }
}

Signed Requests

To ensure that you are receiving an authorized webhook, you may use the HTTP Signature Scheme. You can verify the request without contacting Meshblu to verify it's authenticity.

{
  "meshblu": {
    "forwarders": {
      "version": "2.0.0",
      "message": {
        "sent":     [
          {
            "type": "webhook",
            "url": "http://requestb.in/18gkt511",
            "method": "POST",
            "signRequest": true
          }
        ]
      }
    }
  }
}

The web service will receive an HTTP request with the following headers:

Date: Tue, 17 May 2016 23:44:37 GMT
X-Meshblu-Uuid: 92b50770-203f-4e4a-8b00-1c33ef2be792
X-Meshblu-Message-Type: message.sent
Authorization: Signature keyId="meshblu-webhook-key",algorithm="rsa-sha256",headers="date X-MESHBLU-UUID",signature="g/1Hd1jfjnKEW1ZoHqtJIX2jnAxu350zhBPbPjKr0uOKRuRpeAtuwsxycI2H3/aSZUuBJURGvHQe3h67IGdynYzD1NqNHKeHZi6w8Z+CuDzAECw8k59ZSEsv4YlZzUtJN1WXT0DdITgVjohhj14Otj0k4txpfOqvPRtlI3OwEg4J8fU0RP/snBbypdrJHFcNuNP7143bND/Ga9VzAS4Ytv2a3WGdgvK95cqDri+tNrlzPxmlm0PWyxeOkxIgW7MxQ364jInlKHSYy/lVUkcEZ35GKdAQn6vAHkA+ei3lVSpxYGJfWMc9Tgz23yyiMdHrfnsnuf0qnkz4Tk3XNsPatw=="
X-Request-Id: ac483b2d-f9fb-4d53-a87a-9d891bd003f8

The Authorization header contains a signature that can be verified using the Meshblu public key. The X-MESHBLU-UUID header is part of the signature, so you can trust that the UUID has not been modified.

Forward Meshblu Credentials

Generate a a Meshblu token and send it to the webhook. Sent as an HTTP header Authorization: Bearer <base64 encoded string>. The token will only be valid until the recipient of the Webhook responds to the HTTP request.

❗️

Security Warning

The Bearer token will allow the recipient to access and modify your meshblu device. When the request has finished, the token will be removed.

🚧

unregister.sent and unregister.received

Do not use this option for unregister.sent and unregister.received. The device will not exist when the credentials are used and will immediately fail.

{
  "meshblu": {
    "forwarders": {
      "version": "2.0.0",
      "message": {
				"sent": [
  	      {
    	  		"type": "webhook",
      	    "url": "http://requestb.in/18gkt511",
            "method": "POST",
            "generateAndForwardMeshbluCredentials": true
       	  }
    		]
      }
    }
  }
}

The web service will receive an HTTP request with the following headers.

Date: Tue, 17 May 2016 23:44:37 GMT
X-Meshblu-Uuid: 92b50770-203f-4e4a-8b00-1c33ef2be792
X-Meshblu-Message-Type: message.sent
Authorization: Bearer ZWViMmQ0ZjktMzYwYS00NDFjLTgwZjItZjY0OWNiZWI1ZmU3OmE2OGZjMTRjZGY4YzhmNGQzNWJkY2E1MDMwNDIyYjVkNTQyNzk0NTc=
X-Request-Id: ac483b2d-f9fb-4d53-a87a-9d891bd003f8