diff options
author | Drew DeVault <sir@cmpwn.com> | 2019-04-06 13:05:59 -0400 |
---|---|---|
committer | Drew DeVault <sir@cmpwn.com> | 2019-04-06 13:05:59 -0400 |
commit | cee3f533f4ab4ea8848afa4f6c0b4b87a8505e3e (patch) | |
tree | 674ba1f2d081a0088e84421764b146cdaae15037 /api-conventions.md | |
parent | 84d36e036b9b7981b10d173c682d1160cd99028f (diff) | |
download | sr.ht-docs-cee3f533f4ab4ea8848afa4f6c0b4b87a8505e3e.tar.gz |
Document webhook signatures
Diffstat (limited to 'api-conventions.md')
-rw-r--r-- | api-conventions.md | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/api-conventions.md b/api-conventions.md index 3dbd479..e44b446 100644 --- a/api-conventions.md +++ b/api-conventions.md @@ -178,6 +178,31 @@ resource is encoded via the API. `X-Webhook-Delivery` is set to a UUID assigned to that webhook delivery, and `X-Webhook-Event` is set to the specific event that occurred, e.g. `profile:update`. +### Webhook signatures + +The `X-Payload-Signature` and `X-Payload-Nonce` headers can be used to verify +the authenticity of the webhook payload. Concatenate the request body with the +nonce (treat the nonce as an ASCII-encoded string) and use it to verify the +base64-encoded Ed25519 siganture given by the `X-Payload-Signature` header. The +public key (also base64 encoded) is +`uX7KWyyDNMaBma4aVbJ/cbUQpdjqczuCyK/HxzV/u+4=`. Here's an example of verifying +the payload in Python: + +```python +import base64 +from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey + +public_key = Ed25519PublicKey.from_public_bytes( + base64.b64decode('uX7KWyyDNMaBma4aVbJ/cbUQpdjqczuCyK/HxzV/u+4=')) + +payload = request.data +signature = headers["X-Payload-Signature"] +signature = base64.b64decode(signature) +nonce = headers["X-Payload-Signature"].encode() + +public_key.verify(signature, payload + nonce) +``` + ### Subscription resource ```json |