Format
Important Fields
If you wish to consume exactly the same responses as you get from the API, look under
_restkey. If you also want to see who the object was updated by and what function was used to perform the update, look under thewebhook_metakey which is added to the webhook on creation.
| 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 | Resource | Method |
| http_response_code | string | Response code from webhook URL |
| http_response_text | string | Response text from webhook URL |
| http_responses[] | array of objects | List of response data from webhook URL. See Webhook URL 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, and user 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 assoicated 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 webhook creation date. |
| safe_obj_hash | string | Hashed object information |
| updated_by | string | For internal use |
Webhook URL Response Object
| Key | Type | Description |
|---|---|---|
| date | integer | Date webhook received a response from webhook URL |
| 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 will be 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 that Python (FullBody) listed below uses the entire body of a webhook to create a signature, which can used to rebuild a
X-Synapse-Signature-SHA256-FullBodysignature.
You will be able to rebuild the signature the following way:
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
webhook = '''the webhook json'''
key = bytes('your_client_secret','utf-8')
raw = bytes(webhook,'utf-8')
hashed_sha256 = hmac.new(key, raw, 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 sha1 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.
Additional Information
- Platforms should only send notifications to users if a specific field in the webhook changes. For example, if the status of the transaction changes, you should send an email to your users, but if a new field is added to the webhook response, that should not automatically trigger an email because it does not affect the user