Create Webhook

Create a new webhook configuration. The URL must be HTTPS and respond to test events within 5 seconds. Your endpoint will receive a X-Firma-Signature header containing an HMAC SHA-256 signature that you must verify for security.

Signature Verification: Use your webhook signing secret (available in company settings) to verify the X-Firma-Signature header. During secret rotation, verify against both X-Firma-Signature (new) and X-Firma-Signature-Old (previous secret, valid for 24 hours).

Request Headers Sent:

• X-Firma-Event: Event type (e.g., ‘signing_request.completed’)
• X-Firma-Signature: HMAC SHA-256 signature of payload using current signing secret
• X-Firma-Signature-Old: HMAC SHA-256 signature using previous secret (only during 24-hour rotation grace period)
• X-Firma-Delivery: Unique delivery attempt ID
• User-Agent: ‘Firma-Webhooks/1.0’

Expected Response:

• Status: Any 2xx status code indicates success
• Timeout: Endpoint must respond within 5 seconds
• Body: Optional, max 1000 characters (logged for debugging)

Retry Behavior:

• Failed deliveries are retried 5 times with exponential backoff
• Retry schedule: 1min, 5min, 30min, 2hr, 6hr
• After 50 consecutive failures across all events, webhook is automatically disabled
• Monitor consecutive_failures field and webhook event logs

Best Practices:

• Respond with 2xx immediately, process events asynchronously
• Verify signatures to prevent spoofing
• Handle duplicate events idempotently using event_id
• Store event_id to detect and ignore duplicates
• Monitor consecutive_failures and fix issues promptly

Authorizations

Authorization · string · header · required

API key for authentication. Format: 'Bearer your-api-key'

Body

application/json

url · string<uri> · required

Destination URL for webhook events (must be HTTPS)

Maximum length: 2048

events · enum<string>[] · required

List of event types to subscribe to

Minimum length: 1

Show child attributes

description · string

Maximum length: 500

Response

201

application/json

Webhook created successfully

id · string<uuid> · required

Unique webhook identifier

companies_id · string<uuid> · required

Company ID this webhook belongs to

url · string<uri> · required

Destination URL for webhook events

Maximum length: 2048

enabled · boolean · required

Whether the webhook is active

events · enum<string>[] · required

List of event types this webhook subscribes to

Show child attributes

description · string

Optional description of webhook purpose

Maximum length: 500

consecutive_failures · integer

Number of consecutive delivery failures

last_failure_at · string<date-time>

Timestamp of last delivery failure

created_at · string<date-time>

updated_at · string<date-time>