Vision 6


Creates a new Webhook.


Creates a new Webhook.

Top ↑


int addWebhook( string api_key, object webhook_details );

API Key Access Level required: Full access


api_key (string)

The key required to access the API. See Getting Started for more information.

webhook_details (object)

An object of Webhook details. See remarks below for a description of the values in the webhook_details object.

Return Value

Returns the ID of the newly added Webhook on success.


Creating a new Webhook to receive events when Contacts are unsubscribed:


$api = new Api($url, 'YOURAPIKEY');

$webhook_details = array(
    'object' => 'contact',
    'event' => 'unsubscribed',
    'list_id' => 123,
    'url' => ''

$webhook = $api->invokeMethod('addWebhook', $webhook_details);

JSON Request

    "id": 1,
    "method": "addWebhook",
    "params": [
            "object": "contact",
            "event": "unsubscribed",
            "list_id": 123,
            "url": "http:\/\/\/example.php"

JSON Response

    "id": 1,
    "result": 616,
    "error": null


The following table shows the structure of the webhook_details object.

Key Type Mandatory Default Description
object string Yes Object that the event applies to, either 'list' or 'contact'
event string Yes The event against the object that will trigger this Webhook
list_id int No 0 The List that this Webhook applies to, or 0 to watch all Lists
url string Yes The http/https URL of the receiving Webhook endpoint

The following is a list of the possible event types and which object(s) they apply to:

Event Object Description
created list contact The object was created
updated list contact The object was updated
removed list, contact The object was removed
bulk_updated list A large number of contacts in the list were changed or the list was cleared
subscribed contact The contact was subscribed
unsubscribed contact The contact was unsubscribed
deactivated contact The contact was deactivated
reactivated contact The contact was reactivated

Note: When a contact is manually added and subscribed at the same time, both events will be sent.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
310 Invalid Method Parameters One or more parameters are invalid.
351 Duplicate Webhook details not allowed A webhook with the exact remarks already exists

See Also