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

   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.

When HMAC is Applied

Automatic HMAC Application

HMAC signatures are automatically included in the following scenarios:

• API Nodes in Workflows making HTTP requests to external services
• Webhooks configured in your Vellum organization settings

Manual HMAC Implementation Required

HMAC signatures are NOT automatically included for :

• Code Execution Nodes in Workflows

  If you need to make authenticated requests from within a Code Execution Node, you’ll need to implement HMAC signature generation yourself.

  Manual HMAC Implementation in Code Execution Node

  Consider also storing your HMAC secret as a Workspace Secret for secure access within your Code Execution Nodes.

  Manual HMAC Implementation in Code Execution Node

  1
  import hmac
  2
  import hashlib
  3
  import time
  4
  import requests
  5
  6
  def generate_hmac_headers(secret: str, method: str, url: str, body: str = ""):
  7
      timestamp = str(int(time.time()))
  8
      message = f"{timestamp}\n{method}\n{url}\n{body}"
  9
  10
      hash_object = hmac.new(secret.encode(), msg=message.encode(), digestmod=hashlib.sha256)
  11
      signature = hash_object.hexdigest()
  12
  13
      return {
  14
          'X-Vellum-Timestamp': timestamp,
  15
          'X-Vellum-Signature': signature
  16
      }
  17
  18
  # Example usage in a Code Execution Node
  19
  def main():
  20
      secret = "your-hmac-secret"  # Store this securely
  21
      method = "POST"
  22
      url = "https://your-api.com/endpoint"
  23
      body = '{"key": "value"}'
  24
  25
      headers = generate_hmac_headers(secret, method, url, body)
  26
      headers['Content-Type'] = 'application/json'
  27
  28
      response = requests.post(url, data=body, headers=headers)
  29
      return response.json()

Verifying HMAC Signatures

When Vellum automatically applies HMAC authentication, each request will contain two headers: X-Vellum-Timestamp and X-Vellum-Signature. You can reference these headers to verify the authenticity of requests made to your service from Vellum.

Verification Steps

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

   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.

   Python HMAC Signature Verification Example

   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)