Document webhook signatures

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