HMAC Authetication

This guide will walk you through the process of setting up and using HMAC authentication in Vellum. HMAC authentication provides an additional layer of security for outgoing API calls and webhooks.


  1. Create a new secret token securely: You can do this in Python using the secrets module. Here’s a simple example:
Python Secret Token Generation
1import secrets
  1. Provide your secret token to Vellum: Navigate to the API keys page. Click the “Provide HMAC Token” button and enter your secret token.


Only outgoing webhooks and API calls from Vellum include HMAC authentication.

Each request will contain two headers: X-Vellum-Timestamp and X-Vellum-Signature.

  1. Verify the timestamp: Check that the value of X-Vellum-Timestamp is within the last 60 seconds.

  2. Create the message string: Concatenate the following values together, separated by one newline character, into a new string message:

    • X-Vellum-Timestamp
    • The request method (GET, POST, etc)
    • The request URL
    • The request body
Python HMAC Content
1message = f"{timestamp}\n{method}\n{url}\n{body}"
  1. Verify the signature. Use the HMAC algorithm with SHA-256 to verify the authenticity of X-Vellum-Signature.
Python HMAC Signature Verification Example
1import hmac
2import hashlib
4def verify(message: str, secret: str, signature: str) -> bool:
5 hash_object =, msg=message.encode(), digestmod=hashlib.sha256)
6 expected_signature = hash_object.hexdigest()
7 return hmac.compare_digest(expected_signature, signature)
Was this page helpful?