Security

HMAC Authentication

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:
Python Secret Token Generation
import secrets
print(secrets.token_hex(16))
  1. Provide your secret token to Vellum: Navigate to the API keys page. Click the "Provide HMAC Token" button and enter your secret token.

Usage

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
message = 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
import hmac
import hashlib
def verify(message: str, secret: str, signature: str) -> bool:
hash_object = hmac.new(secret.encode(), msg=message.encode(), digestmod=hashlib.sha256)
expected_signature = hash_object.hexdigest()
return hmac.compare_digest(expected_signature, signature)