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.

Setup

1. Create a new secret token securely: You can do this in Python using the secrets module. Here’s a simple example:

1
import secrets
2
print(secrets.token_hex(16))

2. Provide your secret token to Vellum: Navigate to the API keys page. Click the “Provide HMAC Token” button and enter your secret token.

Usage

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

1
message = f"{timestamp}\n{method}\n{url}\n{body}"

3. Verify the signature. Use the HMAC algorithm with SHA-256 to verify the authenticity of X-Vellum-Signature.

1
import hmac
2
import hashlib
3
4
def verify(message: str, secret: str, signature: str) -> bool:
5
    hash_object = hmac.new(secret.encode(), msg=message.encode(), digestmod=hashlib.sha256)
6
    expected_signature = hash_object.hexdigest()
7
    return hmac.compare_digest(expected_signature, signature)