Available Webhooks

❗️
We support organization-level Webhooks only.
When you subscribe to a webhook, you will receive webhooks for all entries of a given object by default, rather than just for specific users. However, you can create custom configurations to filter the data within the event and determine which events should be forwarded to a specific target.
You must have administrator access to your Maximizer CRM instance in order to manage webhooks.

You can refer to the Webhooks Postman collection to view the latest supported webhooks. In the Payloads folder, you'll find each Maximizer CRM object that currently supports webhooks, along with sample payloads for all available versions. We will explore the contents of this Postman collection in detail later on this page.

In addition to the Postman collection, we have an interactive playground on the developer portal in the API Reference section.

What are Webhooks?

Webhooks are a method of near-real-time communication between applications or systems over the internet. They enable one system to notify another about specific events as they occur. Essentially, a webhook allows an application to send automated updates and/or data to other applications without requiring the receiving system to constantly poll for changes.

Webhooks are commonly used in web development, API integrations, and online services to facilitate the exchange of information between platforms. They are a powerful tool for creating event-driven workflows and system integrations, ensuring timely updates and seamless interactions between applications.

Differences between Webhooks and API

How to work with Webhooks?

Vocabulary

Target: A web service (endpoint) that is ready to accept Maximizer's POST requests.
Subscription: A subscription to a specific webhook. The subscription may include a filter.

Target Requirements

Targets must respond with a 200 OK HTTP code within 2 seconds. If the target has not responded or returns a different HTTP code, we will make two more attempts to deliver the webhook after a short delay.

If the target is unavailable after three attempts, the webhook will be discarded and not delivered.

Webhooks API

The Webhooks API allows you to create your own targets and subscriptions. You can refer to API Reference or the the Webhooks Postman collection for examples of how to use each endpoint.

To use the Webhooks API, you will need:

A token issued to a user of your Maximizer CRM instance. This can be an Octopus (regular or PAT), OAuth, or Ferret token.
The token owner must have an Administrator role. Regular users will not be able to manage webhooks.

In Postman, choose the Webhooks API environment, provide your token in the Token variable, and you are ready to use any request under Management API to manage your targets and subscriptions.

Note: There is a limit on the number of targets you can create for your Maximizer CRM instance. The current limit is 10.

How to Start Receiving Webhooks

Step 1: Create your target service. The target URL can include query parameters.

To secure your URL, you can include a secret in the query parameters or configure the target to send specific headers.

Step 2: Register your target in Maximizer using the Webhooks API.

Step 3: Create a subscription for a specific webhook using the Webhooks API. The subscription can include simple filters, such as "greater than" for numbers or equality checks. You can apply multiple filters, and they will be executed as an AND operation (all filters must match). A list of available operations and usage details can be found in the Postman collection samples.

Step 4: That's it! Once the subscription is created, you'll start receiving webhooks at your target URL. All that’s left is to verify that everything is working as expected.

Check out examples of payloads in the Postman collection.

Webhook's payload

Example of the "Opportunity Stage Change" webhook that are sent to targets:

[
    {
        "Id": "d81f9d6e-8afc-4fa4-9052-2af207494e5d",
        "Timestamp": "2024-09-20T00:01:29.5149836Z",
        "ProcessedTimestamp": "2024-09-20T00:02:45.8974002Z",
        "WorkspaceId": "108F314C-6787-4EE6-BE49-C0E0C651F039",
        "SourceId": "1a0dde7c-743f-4b55-a2bf-e7738393a8e5",
        "Recipients": [],
        "Options": null,
        "Entity": "Opportunity",
        "Data": {
            "Op": "Update",
            "Original": {
                "Key": "T3Bwb3J0dW5pdHkJMjQwOTE5MjUxNjQ1MjA0MTQwMDAxTwkw",
                "SalesProcessSetupKey": "U2FsZXNQcm9jZXNzCTI0MDkxOTI1MTY0NjI3MjU1MDAwMkcJMA==",
                "SalesProcessSetupName": "Sales Process",
                "SalesStageSetupKey": "U2FsZXNQcm9jZXNzU3RhZ2UJMTUyOA==",
                "SalesStageSetupName": "Qualified",
                "Objective": "Test Opportunity",
                "Revenue": 12000.00,
                "UserKey": "VXNlcglNQVNURVI="
            },
            "New": {
                "Key": "T3Bwb3J0dW5pdHkJMjQwOTE5MjUxNjQ1MjA0MTQwMDAxTwkw",
                "SalesStageSetupKey": "U2FsZXNQcm9jZXNzU3RhZ2UJMTUyOQ==",
                "SalesStageSetupName": "Presentation"
            },
            "Version": "1.1"
        }
    }
]

Id: A unique webhook ID.
Timestamp: The timestamp indicating when the webhook was generated at the source.
ProcessedTimestamp: The timestamp indicating when the webhook was processed and forwarded to all subscribed targets.
WorkspaceId: A unique ID for the database from which this webhook was generated.
SourceId: A unique ID for the source that generated the webhook. Note: This is for internal use only and does not carry relevant information for webhook consumers.
Recipients: A list of strings that can be forwarded to the target. For example, this might include a list of specific email addresses for the target to receive when the webhook is forwarded.
Options: Reserved for future use.
Entity: The entity (object name) associated with the webhook.
- Data
  - Op: The name of the operation performed on the entity (e.g., update, delete, create).
  - Original (optional): The original (unchanged) data.
    - Populated for operations: read, update, and delete.
    - Not populated (null) for operations: create.
  - New (optional): The updated (changed) data.
    - Populated for operations: create and update.
    - Not populated (null) for operations: read and delete.
  - Version: Represents the version of the object in the Octopus API. More details are provided in the next section.

Webhooks Versioning

Each webhook contains a Version field within the Data section of the payload. This version corresponds to the version of the object in the source system (e.g., the Octopus API).

If the version is 1.13, the corresponding entity in the source has a major version of 1 and a minor version of 13. The major version indicates breaking changes, while the minor version reflects non-breaking updates.

When implementing your target, it is a best practice to base your implementation on a specific major version of any given entity. This approach prevents breaking your integration if a new major version (with breaking changes) is released in the source system (e.g., the Octopus API).

For any technical questions or discussions - please reach us via Forums