Webhook Documentation

Fired when a contact is subscribed to a message

Example

{
    "type": "subscribe",
    "id": 1572373769.6149,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "survey_id": "1",
    "channel": "Email",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_SUBSCRIBE",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fired when a contact is unsubscribed from a message

Example

{
    "type": "unsubscribe",
    "id": 1572373769.6173,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "survey_id": "1",
    "channel": "Email",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_UNSUBSCRIBE",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a contact is suppressed

Example

{
    "type": "global_unsubscribe",
    "campaignId": null,
    "id": 1572373769.6189,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_GLOBAL_UNSUBSCRIBE",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a contact is reactivated

Example

{
    "type": "reactivated",
    "campaignId": null,
    "id": 1572373769.6192,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_REACTIVATED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a contact is updated

Example

{
    "type": "profile_update",
    "id": 1572373769.6194,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "updated_fields": "{\"1\":\"[email protected]\"}",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_PROFILE_UPDATE",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a message to a contact bounces

Example

{
    "type": "bounced",
    "id": 1572373769.6197,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "survey_id": "1",
    "channel": "Email",
    "reason": null,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_BOUNCED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a contact email address is changed

Example

{
    "type": "email_changed",
    "id": 1572373769.6206,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "old_email": null,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_EMAIL_CHANGED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fired when a message is opened

Example

{
    "type": "opened",
    "id": 1572373769.6208,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "survey_id": "1",
    "channel": "Email",
    "opened_at": "2019-10-29 18:29:29",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_OPENED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fired when a link is clicked in message

Example

{
    "type": "clicked",
    "id": 1572373769.6216,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "survey_id": "1",
    "channel": "Email",
    "click_url": "https:\/\/www.acme.com",
    "url_id": 1,
    "clicked_on": "2019-10-29 13:29:29",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_CLICKED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a survey is created

Example

{
    "type": "survey_created",
    "survey_id": "1",
    "survey_status": "active",
    "survey_type": "survey",
    "tags": "[{\"tagId\":1,\"name\":\"My Tag\"}]",
    "id": 1572373769.6228,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_SURVEY_CREATED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a survey is deleted

Example

{
    "type": "survey_deleted",
    "survey_id": "1",
    "survey_status": "active",
    "survey_type": "survey",
    "tags": "[{\"tagId\":1,\"name\":\"My Tag\"}]",
    "id": 1572373769.6231,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_SURVEY_DELETED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a surveys status has changed (started, stopped and completed)

Example

{
    "type": "survey_status_changed",
    "old_status": "active",
    "new_status": "complete",
    "survey_id": "1",
    "survey_status": "active",
    "survey_type": "survey",
    "tags": "[{\"tagId\":1,\"name\":\"My Tag\"}]",
    "id": 1572373769.6234,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_SURVEY_STATUS_CHANGED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a response is changed. It will contain the answers given in a response.

Example

{
    "type": "response_changed",
    "response": {
        "responseId": 1,
        "ipAddress": "UNKNOWN",
        "responseStart": "2019-09-03 18:44:52",
        "responseComplete": "2019-09-03 18:44:53",
        "isComplete": true,
        "contactId": 1,
        "contactEmail": "[email protected]",
        "personCode": null,
        "1": {
            "response": {
                "choiceId": null,
                "responseValue": "10"
            },
            "questionText": "

How likely are you to recommend ACME to a friend or colleague?<\/p>", "questionId": 1, "questionTypeId": "15", "questionType": "netPromoter", "token": null, "isRequired": false }, "urlVariables": { "myurlvariable": { "name": "myurlvariable", "label": "myurlvariable", "value": null } } }, "sent": "2019-10-29 13:29:29", "survey_id": "1", "survey_status": "active", "survey_type": "survey", "tags": "[{\"tagId\":1,\"name\":\"My Tag\"}]", "id": 1572373769.6237, "email": "[email protected]", "status": "Active", "custom_fields": "{\"name\":null,\"phone\":null}", "ip_created": "", "client_id": "5967", "updated_via": "System", "ip": "127.0.0.1", "action": "WEBHOOK_RESPONSE_CHANGED", "webhook_url": "https:\/\/acme.com\/endpoint", "webhook_key": "amazinglysecurekey" }

Fires when a response is deleted

Example

{
    "type": "response_deleted",
    "responseId": 1,
    "sent": "2019-10-29 13:29:29",
    "survey_id": "1",
    "survey_status": "active",
    "survey_type": "survey",
    "tags": "[{\"tagId\":1,\"name\":\"My Tag\"}]",
    "id": 1572373769.6241,
    "email": "[email protected]",
    "status": "Active",
    "custom_fields": "{\"name\":null,\"phone\":null}",
    "ip_created": "",
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_RESPONSE_DELETED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a tag is created

Example

{
    "type": "tag_created",
    "tag_id": "1",
    "name": "My Tag",
    "id": 1572373769.6244,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_TAG_CREATED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a tag is changed

Example

{
    "type": "tag_changed",
    "tag_id": "1",
    "name": "My Tag",
    "id": 1572373769.6244,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_TAG_CHANGED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}

Fires when a tag is deleted

Example

{
    "type": "tag_deleted",
    "tag_id": "1",
    "name": "My Tag",
    "id": 1572373769.6245,
    "client_id": "5967",
    "updated_via": "System",
    "ip": "127.0.0.1",
    "action": "WEBHOOK_TAG_DELETED",
    "webhook_url": "https:\/\/acme.com\/endpoint",
    "webhook_key": "amazinglysecurekey"
}
<?php 
/*
 * Here’s an example Webhook Endpoint in PHP which receives the data and stores it in a 
 * CSV but it could just as easily go into the database of your choice.
 */ 

// Verify the webhook origin by checking for the Webhook Key value you defined in SurveyTown
if( empty( $_REQUEST['key' ]) || $_REQUEST['key'] != "amazinglysecurekey" ){
    http_response_code(200);
    die();
}

// Look for the response_changed webhook event. Make sure the response is complete before processing.
if( 
    $_REQUEST['type'] == "response_changed" and 
    ! empty( $_REQUEST['response'] ) and 
    $_REQUEST['response']['isComplete'] == 1 
){
    
    $columns = false;
    
    // Use a different CSV file for each survey
    $filename = "survey_responses_{$_REQUEST['survey_id']}.csv";
    
    // Create the CSV header if the file doesn't exist
    if( ! file_exists( $filename ) ){
        $columns = array(
            "ID",
            "IP Address",
            "Start Time",
            "End Time"
        );
    }
    
    // Add response meta data
    $response = array(
        $_REQUEST['response']['responseId'],
        $_REQUEST['response']['ipAddress'],
        $_REQUEST['response']['responseStart'],
        $_REQUEST['response']['responseComplete']
    );
    
    // Loop through all the response data
    foreach( $_REQUEST['response'] as $key => $res ){
        // Questions will have integer keys
        if( is_int( $key ) ){
            // Handle multi value questions
            if( isset( $res['responses'] ) ){
                foreach( $res['responses'] as $choice => $value ){
                    if( $columns ){
                        $columns[] = strip_tags( $res['questionText'] ) . " ({$value['choiceText']})";
                    }
                    $response[] = $value['responseValue'];
                }
                // Handle single value questions
            }elseif( isset( $res['response'] ) ){
                if( $columns ){
                    $columns[] = strip_tags( $res['questionText'] );
                }
                $response[] = $res['response']['responseValue'];
            }
        }
    }
    
    // Open and write to the CSV
    $fp = fopen( $filename, "a" );
    if( $columns ){
        fputcsv( $fp, $columns );
    }
    fputcsv( $fp, $response );
    fclose( $fp );
}

http_response_code(200);