Topics help you organize envelopes and filter webhook event notifications.

​
What Are Topics?

Topics are tags that you can assign to envelopes. You can add up to 10 topics to each envelope. Use topics to:

  • Filter notifications sent by webhooks.
  • Query envelopes based on specific topics.

When creating an envelope, simply add relevant topics in the topics property. You can later query envelopes using these topics as parameters, making it easy to organize related envelopes.

Topics are especially useful for filtering webhook events.

​
How to Filter Webhooks by Topics

SignatureAPI sends webhook notifications whenever an envelope or other resource changes. Topics allow you to filter these events and route notifications effectively.

You can configure webhooks to only emit notifications for envelopes with specific topics. This makes it easier to route webhook notifications to different endpoints, or trigger different workflows.

​
Example: Using Topics in a Company

Imagine a company with two departments: Finance and Sales. Both departments use SignatureAPI for document signing but have distinct workflows for handling finance and sales-related envelopes. Each workflow runs in a different server and have different webhook endpoints.

​
Without Topics:

Without filtering by topics, both workflows (finance and sales) are triggered by all envelopes. This results in confusion, as both departments receive notifications for all envelopes. It leads to unnecessary notifications and requires complex logic to determine which messages are relevant to each department.

​
With Topics:

Topics solve these issues by allowing you to categorize envelopes. By assigning topics to each envelope based on the department or workflow it belongs to, you can configure webhooks to emit notifications only for envelopes with specific topics.

In our example:

  1. Assign Topics:

    • Finance envelopes are created with the topic finance.
    • Sales envelopes are created with the topic sales.
    • Some envelopes might have both topics (finance and sales).

  2. Configure Webhook Endpoints in the Dashboard:

    • Set the topics for each endpoint.
    • The webhook will emit notifications only for envelopes with the specified topics.
    • If no topic is set for a webhook, it will receive notifications for all events.

​
Use Cases for Topics

SignatureAPI customers often use topics to:

  • Categorize envelopes.
  • Trigger different workflows based on departments.
  • Set up a staging endpoint for testing.
  • Tag and control envelope events.

Topics are powerful and flexible—feel free to use them according to your needs.

​
Differences Between Topics and Metadata

SignatureAPI also provides Metadata to store extra information as key-value pairs inside an envelope. Use metadata when you need to store information that links the envelope with your own records. Use Topics when you need to filter or categorize envelopes on SignatureAPI’s side.