8. Webhooks

This section explains how to use rules to create webhooks on CargoX Platform. Webhooks allow you to perform certain actions when a specific event occurs.

8.1. Parameters

Rules are managed through the https://cargox.digital/api/v3/companies/COMPANY_ID/rules/ API endpoint. Allowed methods are GET, POST, PUT, PATCH, DELETE. Each rule you create must have the following arguments:

Argument	Description	Type	Required	Default
name	Name of the webhook.	String	Yes
event	Event ID (see Supported events table).	String	Yes
actions	Array of action objects (see table below for details).	Array	Yes
enabled	Controls if rule is processed or not.	Boolean	No	True

Action objects have the following arguments:

Argument	Description	Required
type	Action ID (see Supported actions table).	Yes
data	Data argument (see Supported actions table).	Depends on action

8.2. Example request

Example request using Bearer access token for authorization. See Authorization and authentication page on how to obtain a bearer token.

curl --location --request POST 'https://cargox.digital/api/v3/companies/COMPANY_ID/rules/' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Notify John and Anne",
    "event": "envelope_received",
    "actions": [
        {
            "type": "send_email_to",
            "data": [
                "[email protected]",
                "[email protected]"
            ]
        }
    ]
}'

8.3. Example response

A call such as the one above will generate the following response:

{
    "id": "e4a9e4bd-f108-49a6-89b5-af534d28a8ea",
    "name": "Notify John and Anne",
    "event": "envelope_received",
    "event_name": "Envelope received",
    "enabled": true,
    "actions": [
        {
            "id": "fd636faa-1437-494e-b5b1-6887e8ec838d",
            "rule_id": "e4a9e4bd-f108-49a6-89b5-af534d28a8ea",
            "type": "send_email_to",
            "type_name": "Send email to",
            "data": [
                "[email protected]",
                "[email protected]"
            ]
        }
    ],
    "actions_description": "Send email to [email protected], [email protected]"
}

8.4. Supported events

Event	Event ID	Description
Envelope received	envelope_received	Triggered when an envelope is received. If the envelope contains documents that transferred via blockchain, this event triggers when all blockchain transactions are confirmed and processed.
Contact invitation accepted	contact_invitation_accepted	Triggered when a sent contact invitation is accepted.

8.5. Supported actions

Action	Action ID	Description	Data required	Data type
Send email to	send_email_to	Sends email to specified email address(es).	Yes	Array of email addresses
Send email to everyone	send_email_to_everyone	Sends email to every user in the company.	No	None
Post webhook	post_webhook	Send an HTTP POST request to a webhook with a serialized envelope as data.	Yes	Array of URL addresses