Webhooks

​

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

​

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.deleted - Signing request deleted (before sending)
• signing_request.certificate.generated - Signing certificate generated
• signing_request.reminder.sent - Reminder sent to recipients

​

Recipient Events

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

​

Template Events

• template.updated - Template modified
• template.used - Template used to create a signing request

​

Organization Seal Events

• organization_seal.created - New seal created
• organization_seal.updated - Seal image replaced (new version), renamed, or default flag changed
• organization_seal.deleted - Seal revoked
• organization_seal.erased - Revoked seal lineage permanently erased

​

Signing Request Seal Events

• signing_request.seal.applied - Seal applied to a document
• signing_request.seal.paused - Seal participant paused (revoked seal with stop pending, or integrity mismatch)
• signing_request.seal.swapped - Paused seal participant swapped to a different seal

​

Workspace Events

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

​

Domain Events

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

​

Two levels of enablement

​

Permissions

​

Creating a webhook

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"
  }'

​

Webhook payload 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)

• X-Firma-Signature - HMAC signature using current signing secret
• X-Firma-Signature-Old - HMAC signature using previous secret (during 7-day rotation grace period)
• X-Firma-Event - Event type (e.g., signing_request.completed)
• X-Firma-Delivery - ID of this event’s delivery to your endpoint. It stays the same on every retry, automatic or manual. Use the payload id to identify the event.

​

Signature format

• 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}
• The HMAC key is your signing secret exactly as shown in the dashboard (64 characters). Don’t hex-decode it.
• X-Firma-Signature and X-Firma-Signature-Old each carry their own t, so read the timestamp from the header you are verifying.

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

​

Get your signing secret

1. Navigate to your Firma dashboard
2. View webhook details to retrieve the signing secret
3. 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')
    
    // This is the secret your endpoint is configured with
    const signingSecret = process.env.FIRMA_WEBHOOK_SECRET
    
    // X-Firma-Signature is signed with Firma's current secret
    if (!verifySignature(payload, signatureHeader, signingSecret)) {
      // During the 7 days after a rotation, X-Firma-Signature-Old is signed with
      // the previous secret, so it matches until you deploy the new secret
      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')
    signature_header_old = request.headers.get('X-Firma-Signature-Old')
    payload = request.get_data(as_text=True)
    
    # This is the secret your endpoint is configured with
    signing_secret = os.environ['FIRMA_WEBHOOK_SECRET']
    
    # X-Firma-Signature is signed with Firma's current secret
    # During the 7 days after a rotation, X-Firma-Signature-Old is signed with
    # the previous secret, so it matches until you deploy the new secret
    if not (verify_signature(payload, signature_header, signing_secret) or
            verify_signature(payload, signature_header_old, 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

1. Firma generates a new secret
2. For 7 days, Firma sends both signatures:

• X-Firma-Signature (new secret)
• X-Firma-Signature-Old (previous secret)

3. After 7 days, only X-Firma-Signature is sent. GET /webhooks/secret-status or GET /workspaces/{id}/webhooks/secret-status returns grace_period_ends_at.

​

If a secret may be compromised

1. Rotate the secret immediately.
2. Deploy the new secret to your endpoint straight away.

​

Retry behavior

• Attempts: Up to 3 per event: immediately, then at least 5 minutes after the first failure, then at least 1 hour after the second. Retries run on a 5-minute cycle, so expect roughly 5 to 10 minutes and 60 to 65 minutes, or later when many retries are queued.
• Timeout: Your endpoint must respond within 5 seconds
• Success: Any 2xx status code indicates success. Redirects count as failures.
• Same event, new signature: Every attempt carries the same X-Firma-Delivery and, for real events, the same payload id, and is signed again with a fresh timestamp. The JSON key order of a retried body can differ from the first attempt, so always verify the raw body exactly as received.
• Auto-disable: When consecutive_failures reaches 50, the webhook is disabled automatically and Firma emails the account owner. Re-enable it with PUT /webhooks/{id} ("enabled": true) or in the dashboard.
• After the last attempt: An event that fails all 3 attempts is not retried automatically. An administrator can retry it from the webhook event log in the dashboard.
• Not retried: Test deliveries from POST /webhooks/{id}/test are sent once. A delivery to a URL that fails Firma’s delivery-time address check (for example, a URL that resolves to a private or loopback address) fails without a retry.

​

Delivery limits

• Events are not delivered in a guaranteed order, and a retried event can arrive after a later one. Use the payload created_at as a hint and fetch the current state from the API.
• Events raised while a webhook or its master switch is off are not stored and are not delivered later. Re-enabling a webhook does not replay them.
• When a webhook already has 100 events from the last 60 seconds, new events for it are skipped and never delivered.
• There is no API to list or replay events. To reconcile after an outage, list signing requests with GET /signing-requests (for example status=finished&sort_by=finished_on&sort_order=desc) and fetch each one with GET /signing-requests/{id}.

​

Idempotency

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

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

• consecutive_failures - Failure counter used for automatic disabling. It resets to 0 after a successful delivery.
• enabled - Whether the webhook is active. It is disabled automatically when consecutive_failures reaches 50.
• auto_disabled_at - When the webhook was disabled automatically, otherwise null

​

Troubleshooting

​

Common issues

• Confirm the master switch is on for the right scope: company-level webhooks need the company’s switch on, workspace-level webhooks need that workspace’s switch on.
• Don’t trust a passing test as proof - POST /webhooks/{id}/test bypasses the master switch, so it can succeed while live events don’t fire.
• Check consecutive_failures on the webhook - if it reads 0 and no events show up, that also points to the master switch, since skipped events are never logged as failed delivery attempts.
• If you can’t find or toggle the master switch, you may not have owner or admin permissions on the company; ask an owner or admin to enable it from Settings > Webhooks.

• 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

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

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

• Check consecutive_failures and recent events in the webhook event log in the dashboard
• Fix endpoint issues, then re-enable webhook via API or dashboard

​

Testing webhooks locally

# 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