Webhook Object Details

Webhook Format

Key	Type	Description
_id.$oid	String	Object ID of webhook
client_id	String	Object ID of Client
date	Integer	Date webhook was created (milliseconds since Unix epoch time)
function	String	Resouce | Method
http_response_code	String	Response code from webhook URL
http_response_text	String	Response text from webhook URL
http_responses[]	Array	List of response data from webhook URL. See Webhook Response Object (below) for more information.
http_url	String	URL webhook was sent to
object_id	String	Object ID attached to resource type
safe_obj._id.$oid	String	Object ID of resource
safe_obj._rest	Object	Contains information about the resource (node, transaction, user, subnet objects)
safe_obj.webhook_meta	Object	Contains information about webhook subscription updates (e.g. who the object was updated by, function used to perform the update, etc)
safe_obj.webhook_meta.function	String	The function associated with the webhook (e.g. "NODE|PATCH")
safe_obj.webhook_meta.log_id	String	The ID of the log associated with the webhook
safe_obj.webhook_meta.updated_by	String	Who updated the webhook subscription (e.g. "SELF", "BACKEND, etc)
safe_obj.webhook_meta.date.$date	Integer (milliseconds since Unix epoch time)	The wehbook creation date
safe_obj_hash	String	Hashed object information
updated_by	String	For internal use

Best key to Query The _rest key is the best key to query by, as it matches what you receive from the API.

Webhook URL Response Object

Key	Type	Description
date	Integer	Date webhook received a response from webhook URL. Use of this value is recommended for ordering webhook responses when receiving them from Synapse.
http_response_code	String	Response code from webhook URL
http_response_text	String	Response text from webhook URL
http_url	String	URL webhook was sent to

HMAC for Webhooks

Every webhook is signed with HMAC.

HMAC is a protocol that helps you judge the authenticity of the received message. This comes in handy when you want to quickly find out whether the webhook was sent by Synapse or a malicious/notorious party.

The signature is a SHA-1 and SHA-256 HMAC hash of the object_id + your client_id, with the secret key as your client_secret.

Please note: Python (FullBody) uses the entire body of a webhook to create a signature, which can be used to rebuild a X-Synapse-Signature-SHA256-FullBody signature.

You will be able to rebuild the signature the following way:

Python

import hmac 
from hashlib import sha1, sha256

key = 'your_client_secret'
raw = '{0}+{1}'.format(payload['_id']['$oid'],'your_client_id')

hashed_sha1 = hmac.new(key, raw, sha1)
hashed_sha256 = hmac.new(key, raw, sha256)

# The signature
print hashed_sha1.hexdigest()
print hashed_sha256.hexdigest()

Python (FullBody)

import hmac
from hashlib import sha1, sha256
import json

payload = {"key": "value"}

webhook = json.dumps(payload,sort_keys=True).encode('utf-8')

key = bytes('your_client_secret','utf-8')

hashed_sha256 = hmac.new(key, webhook, sha256)

# The signature
print(hashed_sha256.hexdigest())

Please note that raw should look like this (with +): 563db3fb86c27307d925871f+e3f19e4bd4022c86e7f2

Not like this (without +): 563db3fb86c27307d925871fe3f19e4bd4022c86e7f2.

Since the SHA-1 signature is in hex, it should look like this:5bce964c20b0c36313d8f7cffc2ff4772d0c96750

We then take this signature and add it into the header of the request with name X-Synapse-Signature and X-Synapse-Signature-Sha256.