Webhooks - Firma

Firma sends webhook events to notify your application about signing lifecycle changes, document completions, and workspace activities. Webhooks enable real-time integrations without polling.

Common use cases

Send internal notifications when documents are signed
Update your database when signing requests are completed
Trigger downstream workflows (invoicing, provisioning, etc.)
Track signing request status changes in real-time

Event types

Firma sends the following event types:

Signing Request Events

signing_request.created - New signing request created
signing_request.sent - Signing request sent to recipients
signing_request.viewed - Recipient viewed the document
signing_request.completed - All recipients finished signing
signing_request.expired - Signing request expired
signing_request.cancelled - Signing request was cancelled
signing_request.updated - Signing request metadata updated
signing_request.certificate.generated - Signing certificate generated
signing_request.reminder.sent - Reminder sent to recipients
signing_request.field.filled - A field was filled by a recipient
signing_request.document.updated - Document was updated

Recipient Events

signing_request.recipient.added - Recipient added to signing request
signing_request.recipient.signed - Recipient completed signing
signing_request.recipient.declined - Recipient declined to sign
signing_request.recipient.updated - Recipient details updated
signing_request.recipient.identity_changed - Recipient changed their identity (name, company, etc.) during signing

Template Events

template.created - New template created
template.updated - Template modified
template.deleted - Template deleted
template.field.added - Field added to template
template.used - Template used to create a signing request

Workspace Events

workspace.created - New workspace created
workspace.updated - Workspace modified
workspace.deleted - Workspace deleted

Domain Events

domain.verified - Domain verified successfully
domain.verification.failed - Domain verification failed

Creating a webhook

Create webhooks via the API or dashboard:

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/firma",
    "events": [
      "signing_request.completed",
      "signing_request.recipient.signed"
    ],
    "description": "Production webhook for signing events"
  }'

Your webhook URL must use HTTPS and respond within 5 seconds. Firma will send a test event during creation to verify the endpoint.

Webhook payload structure

All webhook events follow this standard structure:

{
  "id": "evt_1707500000_k8f2m9x3a",
  "type": "signing_request.completed",
  "created_at": "2025-10-03T14:30:00Z",
  "company_id": "comp_123",
  "workspace_id": "ws_456",
  "data": {
    "signing_request": {
      "id": "sr_789",
      "name": "NDA - Acme Corp",
      "workspace_id": "ws_456",
      "created_at": "2025-10-01T10:00:00Z",
      "sent_at": "2025-10-01T10:05:00Z",
      "completed_at": "2025-10-03T14:29:55Z",
      "cancelled_at": null,
      "expires_at": "2025-10-08T10:05:00Z",
      "document_page_count": 3
    },
    "recipients": [
      {
        "id": "rec_abc",
        "email": "alice@example.com",
        "name": "Alice Johnson",
        "first_name": "Alice",
        "last_name": "Johnson",
        "order": 1,
        "designation": "Signer",
        "signed_at": "2025-10-03T14:29:55Z"
      }
    ],
    "workspace": {
      "id": "ws_456",
      "name": "Legal"
    }
  }
}

Security: Signature verification (Required)

Always verify webhook signatures to prevent spoofing attacks. Do not process webhooks without signature verification.

Firma signs all webhook requests using HMAC SHA-256. Your webhook endpoint receives these headers:

X-Firma-Signature - HMAC signature using current signing secret
X-Firma-Signature-Old - HMAC signature using previous secret (during 24-hour rotation grace period)
X-Firma-Event - Event type (e.g., signing_request.completed)
X-Firma-Delivery - Unique delivery attempt ID

Signature format

Firma uses a timestamped signature header:

Header: X-Firma-Signature: t=1707500000,v1=abc123def456...
t = Unix timestamp (seconds) when the signature was generated
v1 = HMAC-SHA256 hex digest
Signed payload format: {timestamp}.{json_body}

Example:

1707500000.{"id":"evt_123","type":"signing_request.completed",...}

Get your signing secret

Navigate to your Firma dashboard
View webhook details to retrieve the signing secret
Store the secret securely (environment variable or secrets manager)

Verification example — Node.js (Express)

import express from 'express'
import crypto from 'crypto'

const app = express()

// Use raw body for signature verification
app.post('/webhooks/firma', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signatureHeader = req.headers['x-firma-signature']
    const signatureHeaderOld = req.headers['x-firma-signature-old']
    const payload = req.body.toString('utf8')
    
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // Verify with current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During secret rotation, also check old signature header
      if (!signatureHeaderOld || !verifySignature(payload, signatureHeaderOld, signingSecret)) {
        console.error('Invalid webhook signature')
        return res.status(401).json({ error: 'Invalid signature' })
      }
    }
    
    // Parse and process event
    const event = JSON.parse(payload)
    processWebhookEvent(event)
    
    // Respond immediately
    res.status(200).json({ received: true })
  }
)

function verifySignature(payload, signatureHeader, secret) {
  if (!signatureHeader) return false

  // 1. Parse signature header: "t=1707500000,v1=abc123..."
  const parts = {}
  signatureHeader.split(',').forEach(part => {
    const [key, value] = part.split('=')
    parts[key] = value
  })

  const timestamp = parts.t
  const signature = parts.v1

  if (!timestamp || !signature) return false

  // 2. Optional: Reject old timestamps to prevent replay attacks (5 min tolerance)
  const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)
  if (timestampAge > 300) {
    console.warn('Webhook timestamp too old:', timestampAge, 'seconds')
    return false
  }

  // 3. Reconstruct the signed payload (timestamp + "." + raw JSON body)
  const signedPayload = `${timestamp}.${payload}`

  // 4. Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  // 5. Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  } catch {
    return false
  }
}

async function processWebhookEvent(event) {
  // Process asynchronously - don't block the response
  switch (event.type) {
    case 'signing_request.completed':
      await handleSigningCompleted(event.data)
      break
    case 'signing_request.recipient.signed':
      await handleRecipientSigned(event.data)
      break
    // ... handle other event types
  }
}

app.listen(3000)

Verification example — Python (Flask)

from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import time
import json

app = Flask(__name__)

@app.route('/webhooks/firma', methods=['POST'])
def firma_webhook():
    signature_header = request.headers.get('X-Firma-Signature')
    payload = request.get_data(as_text=True)
    
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # Verify signature
    if not verify_signature(payload, signature_header, signing_secret):
      return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse and process event
    event = json.loads(payload)
    process_webhook_event(event)
    
    # Respond immediately
    return jsonify({'received': True}), 200

def verify_signature(payload, signature_header, secret):
  if not signature_header:
    return False

  # Parse "t=1707500000,v1=abc123..."
  parts = dict(p.split('=') for p in signature_header.split(','))
  timestamp = parts.get('t')
  signature = parts.get('v1')

  if not timestamp or not signature:
    return False

  # Optional: Check timestamp age (5 min tolerance)
  if int(time.time()) - int(timestamp) > 300:
    return False

  # Reconstruct signed payload
  signed_payload = f"{timestamp}.{payload}"

  # Compute expected signature
  expected_signature = hmac.new(
    secret.encode('utf-8'),
    signed_payload.encode('utf-8'),
    hashlib.sha256
  ).hexdigest()

  return hmac.compare_digest(signature, expected_signature)

def process_webhook_event(event):
    # Process asynchronously - don't block the response
    event_type = event['type']
    
    if event_type == 'signing_request.completed':
        handle_signing_completed(event['data'])
    elif event_type == 'signing_request.recipient.signed':
        handle_recipient_signed(event['data'])
    # ... handle other event types

if __name__ == '__main__':
    app.run(port=3000)

Handling secret rotation

When you rotate your webhook signing secret:

Firma generates a new secret
For 24 hours, Firma sends both signatures:
- X-Firma-Signature (new secret)
- X-Firma-Signature-Old (previous secret)
After 24 hours, only X-Firma-Signature is sent

Implementation: Check X-Firma-Signature first. If verification fails and X-Firma-Signature-Old exists, verify against the old secret.

Retry behavior

Firma automatically retries failed webhook deliveries:

Retry schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours
Total attempts: Up to 5 retries per event
Timeout: Your endpoint must respond within 5 seconds
Success: Any 2xx status code indicates success
Auto-disable: After 50 consecutive failures, the webhook is automatically disabled

Best practice: Respond with 200 immediately, then process events asynchronously (queue, background job, etc.) to avoid timeouts.

Idempotency

Always handle duplicate events using the event id:

async function processWebhookEvent(event) {
  // Check if already processed
  const exists = await db.webhookEvents.findOne({ event_id: event.id })
  if (exists) {
    console.log(`Event ${event.id} already processed`)
    return
  }
  
  // Store event id to prevent duplicates
  await db.webhookEvents.create({ event_id: event.id, processed_at: new Date() })
  
  // Process event
  // ...
}

Monitoring webhook health

Monitor your webhook’s health by checking the webhook details:

## Get webhook details
curl "https://api.firma.dev/functions/v1/signing-request-api/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes:

consecutive_failures - Number of consecutive failed deliveries
last_failure_at - Timestamp of most recent failure
enabled - Whether webhook is active (auto-disabled after 50 failures)
last_success_at - Timestamp of most recent successful delivery

Rate limit: GET webhook requests support 60 requests per minute per API key.

Troubleshooting

Common issues

401 Unauthorized / Invalid signature

Verify you’re using the correct signing secret
Check that you’re hashing the raw request body (not parsed JSON)
Ensure you’re using HMAC SHA-256, not other hash algorithms

Timeouts / 504 errors

Respond with 200 immediately, process asynchronously
Check your endpoint responds within 5 seconds
Use background jobs/queues for heavy processing

Duplicate events

Implement idempotency using the event id
Store processed event IDs in your database

Webhook auto-disabled

Check consecutive_failures and recent event logs
Fix endpoint issues, then re-enable webhook via API or dashboard

Testing webhooks locally

Use a tunnel service like ngrok for local development:

# Start ngrok
ngrok http 3000

# Use the HTTPS URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/firma

Production checklist

Verify HMAC signatures on all webhook requests
Handle signature rotation (check both X-Firma-Signature and X-Firma-Signature-Old)
Respond with 200 within 5 seconds
Process events asynchronously (queues/background jobs)
Implement idempotency using the event id
Store signing secret securely (env var or secrets manager)
Monitor consecutive_failures metric via GET webhook endpoint
Set up alerts for webhook failures
Log all webhook events for debugging
Test with all subscribed event types
Stay within rate limits (See Rate Limit Guide)

Next steps

Create a webhook via API
Test your webhook before going live
Update webhook settings as needed

​Common use cases

​Event types

​Signing Request Events

​Recipient Events

​Template Events

​Workspace Events

​Domain Events

​Creating a webhook

​Webhook payload structure

​Security: Signature verification (Required)

​Signature format

​Get your signing secret

​Verification example — Node.js (Express)

​Verification example — Python (Flask)

​Handling secret rotation

​Retry behavior

​Idempotency

​Monitoring webhook health

​Troubleshooting

​Common issues

​Testing webhooks locally

​Production checklist

​Next steps

Common use cases

Event types

Signing Request Events

Recipient Events

Template Events

Workspace Events

Domain Events

Creating a webhook

Webhook payload structure

Security: Signature verification (Required)

Signature format

Get your signing secret

Verification example — Node.js (Express)

Verification example — Python (Flask)

Handling secret rotation

Retry behavior

Idempotency

Monitoring webhook health

Troubleshooting

Common issues

Testing webhooks locally

Production checklist

Next steps