Links

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
Python (FullBody)
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()
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.