Skip to main content
Skip table of contents

1. Webhook Management

Webhook Management

This scenario demonstrates how to create, retrieve, and manage webhooks in the Circularo system. Webhooks provide a powerful mechanism for receiving real-time notifications about document events, enabling seamless integration with your existing systems and workflows.

Key features:

  • Create webhooks to receive real-time notifications about document events

  • Secure webhook communications using HMAC signature verification

  • Retrieve existing webhooks to monitor your integration points

  • Delete webhooks when they are no longer needed

Understanding Webhooks

Webhooks are HTTP callbacks that notify your systems when specific events occur in Circularo:

  • Real-time Notifications: Receive immediate updates when documents are created, signed, or completed

  • System Integration: Connect Circularo with your existing business systems and workflows

  • Automation Enablement: Trigger automated processes based on document events

  • Reduced Polling: Eliminate the need for frequent API calls to check document status

Webhook Scope and Security

When creating webhooks, it's important to understand their scope and security implications:

  • Organization-Level Scope: Webhooks created by organization administrators cover all documents within their organization

  • Tenant-Level Scope: Webhooks created by global administrators can target either the entire tenant or a specific organization

  • HMAC Verification: Optional HMAC secret for verifying webhook authenticity using SHA-256 signatures

  • Comprehensive Coverage: Webhooks target all events within their scope; they cannot be limited to specific documents or actions

Webhook endpoints must be publicly accessible and capable of receiving HTTP POST requests. Ensure your endpoint is properly secured and can handle the expected volume of notifications.

Prerequisites

Before managing webhooks, you need:

  • A valid authentication token with appropriate permissions ("use_webhooks")

  • A publicly accessible URL that can receive webhook notifications

  • For secure webhooks: A secret key for HMAC signature verification

Step 1 - Create a Webhook

This endpoint demonstrates how to create a webhook that will notify your system about document events in your organization. Once configured, the webhook will send HTTP POST requests to your specified URL whenever relevant events occur.

  • Creates a webhook that monitors all document events within your organization

  • Configures the callback URL where notifications will be sent

  • Optionally sets up HMAC signature verification for enhanced security

  • Begins sending notifications immediately after creation

As an organization administrator, you can only create webhooks for your own organization.

Endpoint

CODE 
POST /webhooks

Request

JSON 
POST /webhooks?token=TYDDbuVgdmnl30GrTN8hmTX6BjqIBstyJNv5KosxFWkyH1SbqeI8KLstKDDHmsFN

Content-Type: application/json

{
  "type": "organization",  //Type of webhook - 'organization' monitors all documents in your organization
  "callbackUrl": "https://webhook.site/7d041a97-550a-4e9f-97c9-66547b4807a3",  //URL that will receive webhook notifications as HTTP POST requests
  "hmacSecret": "Gh1!f5dFs0dA"  //Optional secret key for HMAC signature verification
}

Response

JSON 
{
  "id": "fHgWAoL8BAet7hOb3zy0",  //Unique identifier for the webhook
  "creator": "john.doe@circularo.com",  //User who created the webhook
  "createDate": "2023-07-19T10:30:25.542Z",  //When the webhook was created
  "type": "organization",  //Type of webhook (organization or tenant)
  "name": "494f4f2f-4215-452c-b004-1bcad4706626",  //Organization ID associated with this webhook
  "callbackUrl": "https://webhook.site/7d041a97-550a-4e9f-97c9-66547b4807a3",  //URL that will receive webhook notifications
  "hmacSecret": "Gh1!f5dFs0dA"  //Secret key for HMAC signature verification
}

The response contains the following important properties:

  • webhookId - Located at id in the response.

    • Unique identifier for the webhook

    • Example value: fHgWAoL8BAet7hOb3zy0

The webhook has been successfully created and will now notify your system about document events within your organization.

Webhook Notification Format

Your callback URL will receive HTTP POST requests with JSON payloads similar to this:

JSON 
{
  "documentId": "e2461c31-9d65-472d-8d85-90bcefbac3f7",
  "event": "documentCompleted",
  "actor": "john.smith@example.com",
  "timestamp": "2023-07-19T12:30:00.152Z"
}

Common Event Types

  • documentCreated: A new document has been created

  • signRequest: A document has been shared with recipients for signing

  • documentSigned: A document has been signed by a user

  • documentCompleted: All required signatures have been collected

  • signRejected: A recipient has rejected the document

Security Verification

When an HMAC secret is provided, each webhook request will include an `x-circularo-signature` header containing a SHA-256 HMAC signature of the request body. Your server should verify this signature to ensure the request is authentic:

JAVASCRIPT 
// Example verification in Node.js
const crypto = require('crypto');

function verifyWebhookSignature(requestBody, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = hmac.update(requestBody).digest('hex');
  return calculatedSignature === signature;
}

You can use services like webhook.site for testing webhooks during development. For production, ensure your endpoint can handle the expected volume of notifications and implements proper security measures.

Step 2 - Retrieve Existing Webhooks

This endpoint demonstrates how to retrieve a list of all webhooks that you have access. This is useful for monitoring your integration points and verifying webhook configurations.

  • Returns a list of all webhooks you have access

  • Includes details such as callback URLs, webhook types, and creation dates

  • Helps you manage and monitor your webhook integrations

  • Provides webhook IDs needed for deletion or modification

Organization administrators will only see webhooks for their organization, while global administrators can see all webhooks in the system.

Endpoint

CODE 
GET /webhooks

Request

JSON 
GET /webhooks?token=TYDDbuVgdmnl30GrTN8hmTX6BjqIBstyJNv5KosxFWkyH1SbqeI8KLstKDDHmsFN

Response

JSON 
{
  "total": 3,  //Total number of webhooks
  "results": [  //Array of webhook configurations
    {
      "id": "fHgWAoL8BAet7hOb3zy0",  //Unique identifier for the webhook
      "creator": "john.doe@circularo.com",  //User who created the webhook
      "createDate": "2023-07-19T10:30:25.542Z",  //When the webhook was created
      "type": "organization",  //Type of webhook (organization or tenant)
      "name": "494f4f2f-4215-452c-b004-1bcad4706626",  //Organization ID associated with this webhook
      "callbackUrl": "https://webhook.site/7d041a97-550a-4e9f-97c9-66547b4807a3",  //URL that will receive webhook notifications
      "hmacSecret": "Gh1!f5dFs0dA"  //Secret key for HMAC signature verification (visible to the webhook creator only)
    },
    ...
  ]
}

The response contains a list of all webhooks you have access, along with their configuration details.

  • The total field indicates the total number of webhooks you have access

  • The results array contains detailed information about each webhook

  • Each webhook entry includes its ID, type, callback URL, and other configuration details

  • Use this information to manage your webhook integrations and verify their settings

Step 3 - Delete a Webhook

This endpoint demonstrates how to delete a webhook when it is no longer needed. Deleting a webhook immediately stops all notifications to the associated callback URL.

  • Permanently removes the webhook from the system

  • Immediately stops all notifications to the associated callback URL

  • Requires the webhook ID obtained from the creation response or webhook listing

  • Cannot be undone - to restore notifications, you must create a new webhook

Endpoint

CODE 
DELETE /webhooks/:webhookId

Request

JSON 
DELETE /webhooks/fHgWAoL8BAet7hOb3zy0?token=TYDDbuVgdmnl30GrTN8hmTX6BjqIBstyJNv5KosxFWkyH1SbqeI8KLstKDDHmsFN

Response

JSON 
{
  "status": "SUCCESS"
}

The webhook has been successfully deleted and will no longer send notifications to the callback URL.

  • All notifications to the associated callback URL have been stopped

  • The webhook has been permanently removed from the system

  • To restore notifications, you must create a new webhook

If you need to modify a webhook's configuration (such as changing the callback URL or HMAC secret), you must delete the existing webhook and create a new one with the updated settings.

Webhook Management Summary

You have successfully learned how to create, retrieve, and delete webhooks in the Circularo system. Webhooks provide a powerful mechanism for receiving real-time notifications about document events, enabling seamless integration with your existing systems and workflows.

Key Concepts

  • Webhook Creation: Setting up notification endpoints for real-time event monitoring

  • Webhook Scope: Understanding the coverage of webhooks at organization or tenant level

  • Security Verification: Using HMAC signatures to verify webhook authenticity

  • Webhook Management: Retrieving and deleting webhooks as needed

Common Use Cases

  • Document Workflow Automation: Trigger processes when documents are created, signed, or completed

  • Integration with External Systems: Connect Circularo with CRM, ERP, or other business systems

  • Notification Systems: Alert users or administrators about important document events

  • Audit and Compliance: Track document activities in real-time for compliance purposes

Next Steps

With your understanding of webhook management, you can now:

  • Implement webhook receivers in your systems to process Circularo notifications

  • Set up secure verification of webhook requests using HMAC signatures

  • Create automated workflows triggered by document events

  • Explore the second part of this section to learn about receiving and processing webhook notifications

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT 
// Webhook management example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_AUTH_TOKEN"; // Obtained from login or API key
const CALLBACK_URL = "https://your-server.com/webhook-endpoint";
const HMAC_SECRET = "YourSecretKey123!"; // Secret for signature verification

try {
    // Step 1: Create a webhook
    const createResponse = await fetch(`${URL}${API_PATH}/webhooks?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            type: "organization",
            callbackUrl: CALLBACK_URL,
            hmacSecret: HMAC_SECRET
        })
    });
    if (!createResponse.ok) {
        throw new Error(`Webhook creation failed: ${createResponse.status} ${createResponse.statusText}`);
    }

    const webhookData = await createResponse.json();
    console.log(`Webhook created with ID: ${webhookData.id}`);

    // Step 2: Retrieve all webhooks
    const listResponse = await fetch(`${URL}${API_PATH}/webhooks?token=${TOKEN}`);
    if (!listResponse.ok) {
        throw new Error(`Failed to retrieve webhooks: ${listResponse.status} ${listResponse.statusText}`);
    }

    const webhooksData = await listResponse.json();
    console.log(`Found ${webhooksData.total} webhooks`);

    // Display webhook details
    webhooksData.results.forEach((webhook) => {
        console.log(`Webhook ID: ${webhook.id}`);
        console.log(`Type: ${webhook.type}`);
        console.log(`Callback URL: ${webhook.callbackUrl}`);
        console.log(`Created by: ${webhook.creator} on ${new Date(webhook.createDate).toLocaleString()}`);
        console.log('---');
    });

    // Step 3: Delete a webhook (when no longer needed)
    const deleteResponse = await fetch(`${URL}${API_PATH}/webhooks/${webhookData.id}?token=${TOKEN}`, {
        method: 'DELETE'
    });
    if (!deleteResponse.ok) {
        throw new Error(`Webhook deletion failed: ${deleteResponse.status} ${deleteResponse.statusText}`);
    }

    const deleteResult = await deleteResponse.json();
    console.log(`Webhook deleted successfully: ${deleteResult.status}`);

} catch (error) {
    console.error('Error managing webhooks:', error.message);
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close