Send Webhook

The Send webhook action allows you to set up integrations that subscribe to certain event. When one of those events is triggered, SuperAnnotate will send an HTTP POST payload to the configured Request URL.

Configuration

To set up your webhook, you need to provide the following information:

• Request URL: The URL of the server that will receive the POST requests triggered by the subscribed events.
• Secret (optional): A random string that enhances security by securing your messages with HMAC.

Setting a Secret allows you to validate that POST requests sent to the Request URL originate from SuperAnnotate. This is an optional step that provides additional security for your webhook. When a Secret is set, SuperAnnotate uses HMAC to compute its hash signature. This hash signature is included in the header of each request as X-Authorization-Content-Sha256, which can be used on the server side to validate whether the request originated from SuperAnnotate.

🚧

Limitations and restrictions

• Method: The webhook sends data to the Request URL using the HTTP POST method.
• Concurrency: The action has a concurrency limit of 32 requests at the same time.
• Response Status Codes: Status codes between 200 and 299 in responses will be considered successful.
• Response Timeout: The response timeout for webhook requests is set to 30 seconds. If the endpoint does not respond within this time frame, the request will be considered failed.

HTTP Request

Headers

The HTTP POST request will include the following headers; see the key dictionary here.

{  
    "Accept": "application/json;charset=UTF-8",  
    "X-Event": "project c>",  
    "X-Delivery": "1704335",  
    "Content-Type": "application/json",  
    "X-Authorization-Content-SHA256": "aff4a096a2cea275e1b4cfb5ea1724983bdb82895e"  
}

Payload

The payload sent in the HTTP POST request includes JSON-formatted data containing information about the event that triggered the action. Here's an example payload; see the key dictionary.

{
    "before": null,
    "after": {
        "id": 0,
        "team_id": 0,
        "project_id": 0,
        "folder_id": 0,
        "name": "image_1.jpg",
        "annotation_status": "New",
        "annotator_id": "[email protected]",
        "annotator_name": "Annotator Name",
        "qa_id": "[email protected]",
        "qa_name": "QA Name",
        "createdAt": 1727269829000,
        "updatedAt": 1727269829000,
        "approval_status": null,
        "organization_id": "0"
    },
    "op": "c",
    "ts_ms": 1727269829270
}

Send email

The Send Email action allows you to send email notifications whenever a certain event happens at SuperAnnotate.

Configuration

To configure email notifications, you only need to provide the list of recipients' email addresses. Emails can only be sent to existing team members.

🚧

Limitations and restrictions

• Recipients: Emails can only be sent to existing team members.
• Events: The action cannot be linked to the “Incoming webhook”, “Periodic event” and item-related events.

Email body

The email body is automatically generated based on the event that triggered the action, as well as the location identifiers. The email is sent in plain text format. Here's an example:

Event - "Project status updated"
From Value - "NotStarted"
To Value - "InProgress"
Triggered by - "MyTeam/MyProject/MyFolder"

• Event: Information about the event that triggered the action.
• From Value: If applicable, the "from" data or value associated with the event.
• To Value: If applicable, the "to" data or value associated with the event.
• Triggered by: Indicates the team, project, and folder that initiated the event, formatted as a location path <team_name>/<project_name>/<folder_name>. In this case, the event was triggered by the MyFolder folder within the MyProject project of the MyTeam team.

Custom action

The Custom action is a specific action that a user manually writes and builds through a code editor. This allows users to define the exact behavior and functionality they need whenever a certain event happens at SuperAnnotate. For instance, users have the ability to write Python code using the SuperAnnotate SDK to execute their desired actions. Check how to create Custom Actions here.

When a custom action is triggered, the handler function receives Event and Context objects in the Input JSON, detailing the event and providing contextual information. The Output JSON can include text or a traceback, summarizing the action's execution and any outcomes. Logs are also generated for the action run, aiding in troubleshooting and monitoring. You can monitor all of these, including custom action results here.

Configuration

To include a custom action in your pipeline, first create the custom action, then navigate to the pipeline editor and select the custom action card from the available actions list in the left panel.

Within the pipeline editor, the following configurations are available for custom actions:

• Secret: If your custom action requires secure variables (e.g., SDK tokens or external service credentials), create a Secret containing all the necessary variables and mount it to the custom action. For more details, refer to the setup guide here.
• Event Object Customization: By default, SuperAnnotate sends a predefined event object. You can customize the behavior of your function by adding custom arguments from the "Event Object" section in the right panel of the custom action card within the pipeline editor.

🚧

Limitations and restrictions

• Concurrency: Custom actions are limited to a maximum concurrency of 32 instances. If this limit is reached, additional actions will be queued and executed once a slot becomes available.
• Time to Live (TTL): Custom actions have a TTL of 3 hours. This means that once a custom action is triggered and its status changes to pending, it must be completed within 3 hours. If an action takes longer than 3 hours to complete, it will be marked as failed.

Input JSON

The “Input” refers to the data or parameters that are passed into the function when it is called. This can include any information that the function needs to perform its task, such as variables, objects, or other data. The Input JSON contains two main objects: "event" and "context".

Event Object

This object provides details about the event that triggered the handler function, which you also can modify as described above. Here's an example:

{  
    "uuid": 1704326,  
    "event": "project c",  
    "pipeline_id": 5249,
    "trigger_result_id": 3456
}

For more information on the event’s key structure, refer to the key dictionary.

Context Object

This object provides the input data passed to the function, including a trigger payload. Here's an example:

{
    "op": "c",
    "after": {
        "id": 0,
        "name": "MyProject",
        "type": "Vector",
        "status": "NotStarted",
        "options": 0,
        "team_id": 0,
        "createdAt": 1718965118000,
        "deletedAt": 0,
        "is_pinned": false,
        "updatedAt": 1718965118000,
        "creator_id": "[email protected]",
        "description": null,
        "upload_state": "Initial",
        "entropy_status": "NotStarted",
        "sharing_status": null,
        "attachment_name": null,
        "attachment_path": null,
        "custom_editor_url": null
    },
    "ts_ms": 1718965118466,
    "before": null
}

For more information on the context’s key structure, refer to the key dictionary.