WebHooks

In this section we will describe all available methods for working with Webhooks via API.

You can read more about the webhooks format here

Table of Contents

Common information

  • The number of webhooks on one account is limited to 100
  • One webhook can be associated with several events

List of webhooks

Method

GET /api/v4/webhooks

Description

This method allows to get a list of webhooks on the account.

Limitations

Method is available for administrator users only.

GET parameters

Parameter Data type Description
filter object Filter
filter[destination] string Filter by the webhook URL

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized

Response parameters

Method returns a collection of webhook models. The properties of the model are listed below

Parameter Data type Description
id int Webhook ID
created_by int ID of the user who created the webhook
created_at int Webhook creation date in the format of Unix Timestamp
updated_at int Webhook edit date in the format of Unix Timestamp
sort int Webhook sorting
disabled bool Defines whether webhook is disabled
destination string Valid URL where you want to receive a notification
settings array Webhook trigger events. You’ll find a list of available events here

Response example


{
    "_total_items": 2,
    "_embedded": {
        "webhooks": [
            {
                "id": 839656,
                "destination": "https://webhook-uri.com",
                "created_at": 1575539157,
                "updated_at": 1575539157,
                "account_id": 321321,
                "created_by": 123123,
                "sort": 1,
                "disabled": false,
                "settings": [
                    "add_task"
                ]
            },
            {
                "id": 849193,
                "destination": "https://api.test.com/amoWebHook",
                "created_at": 1576157524,
                "updated_at": 1585816857,
                "account_id": 321321,
                "created_by": 123123,
                "sort": 2,
                "disabled": true,
                "settings": [
                    "update_lead"
                ]
            }
        ]
    }
}
        

Adding webhooks

Method

POST /api/v4/webhooks

Description

This method allows to create a webhook to receive event notifications to the specified URL.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To create a webhook, “destination” and “settings” parameters should be passed. If a webhook with the passed destination already exists, it will be updated corresponding to the passed settings.

Parameter Data type Description
destination string Valid URL where you want to receive a notification
settings array Webhook trigger events. Passed as an array of events. You’ll find a list of available events here

An example of the request


{
    "destination": "https://example.test",
    "settings": [
        "add_lead"
    ],
    "sort": 10
}
        

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Webhook added successfully
422 Request can not be processed. Details are available in the request response
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns the added webhook model. The properties of the model are similar to the model returned in the Webhooks List request responce.

Response example


{
    "id": 1056949,
    "destination": "https://example.test",
    "created_at": 1589012268,
    "updated_at": 1589012268,
    "account_id": 321321,
    "created_by": 3944275,
    "sort": 1,
    "disabled": false,
    "settings": [
        "add_lead"
    ]
}
        

Deleting a webhook

Method

DELETE /api/v4/webhooks

Description

This method allows to delete a webhook.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 Webhook has been deleted successfully
404 Webhook is not found
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body

Webhook events

Event Description
responsible_lead Lead responsible user changed
responsible_contact Contact responsible user changed
responsible_company Company responsible user changed
responsible_customer Customer responsible user changed
responsible_task Task responsible user changed
restore_lead Deleted lead restored
restore_contact Deleted contact restored
restore_company Deleted company restored
add_lead Lead added
add_contact Contact added
add_company Company added
add_customer Customer added
add_task Task added
update_lead Lead updated
update_contact Contact updated
update_company Company updated
update_customer Customer updated
update_task Task updated
delete_lead Lead deleted
delete_contact Contact deleted
delete_company Company deleted
delete_customer Customer deleted
delete_task Task deleted
status_lead Lead status changed
note_lead Note added to lead
note_contact Note added to contact
note_company Note added to company
note_customer Note added to customer