Webhooks

Webhooks are HTTP callbacks that notify your application when specific events occur in covosign. Instead of repeatedly checking the API for status updates (polling), your server receives instant notifications, enabling real-time integrations and automated workflows. This push-based approach is more efficient and responsive than pull-based polling.

Event Types

covosign sends different types of webhook events to keep you informed about the signing process. Each event type corresponds to a specific action or state change in the signature workflow. By listening to these events, you can trigger appropriate actions in your application, such as updating databases, sending notifications, or initiating downstream processes.

Use webhooks to update internal systems, trigger automations, or notify users without polling the API.

• SIGNATURE_REQUEST_COMPLETED: All parties have executed their signatures on the document.
• SIGNATURE_REQUEST_DECLINED: A recipient has declined to sign the document.
• RECIPIENT_SIGNED: An individual recipient has completed their signature.
• RECIPIENT_ADDED: A new signer has been added to the signature request.

Webhook Process Flow

Security Implementation (HMAC)

Webhook security is crucial to prevent malicious actors from sending fake notifications to your endpoints. covosign uses HMAC (Hash-based Message Authentication Code) signatures to verify that webhook payloads are authentic and haven't been tampered with. You should always validate the signature on your server before processing the webhook data.

Important: Never expose your Webhook Secret in client-side code. Verification must happen on your secure backend server.

HMAC Verification Process

Node.js

const crypto = require('crypto');

const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const isValid = expected === receivedSignature;

Python

import hmac
import hashlib

expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
is_valid = expected == received_signature

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
mac.init(secretKey);
byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
String expected = bytesToHex(hash);
boolean isValid = expected.equals(receivedSignature);

Bash

# Using openssl for HMAC verification
expected=$(echo -n "$payload" | openssl dgst -sha256 -hmac "$secret" -hex | cut -d' ' -f2)
if [ "$expected" = "$received_signature" ]; then
    echo "Valid signature"
else
    echo "Invalid signature"
fi

Delivery and Retry Policy

• Exponential backoff retries are applied for non-200 HTTP responses.
• Validate the X-covosign-Signature header in all webhook requests.
• Ensure rapid response times (within seconds) to prevent timeout issues.