Webhooks

Webhooks are a service provided by CleverReach for you to be proactively informed on certain events.
For a list of available events, please see "Available Events".

Endpoints

There are three endpoints to register and manage your webhooks.

Take care to use a valid access_token for all these endpoints, containing the according scope!

Available Events

receiver

form

filter

group

automation

Registering to an Event

You can register a complete event category or a specific event.
So you could register either receiver if you are interested in all events of that category or you can just register for receiver.subscribed if that's the only event you want to know about.

Registering to an event is one call including a verification process.
The initial data to be sent looks something like the following:

{
    "url":       "https://hook.waynecorp.gc/cleverreach",
    "event":     "receiver",
    "condition": "1939",
    "verify":    "damnSecretBatTokenForVerify"
}

Verfication Process

While the URL you provide is called on events using POST, the same URL is used for verification using GET.

Your Endpoint (GET)

For verificytion purposes, your endpoint is called using GET with an URL parameter: secret.
Simply return the verify token you provided earlier and the value of that parameter, concatenated with a space in between.
Assuming the verify token from above and the parameter secrect=1029384756 we would return this string:

damnSecretBatTokenForVerify 1029384756

A successful registration process returns the following data:

{
    "success":    true,
    "call_token": "a#64characters-longtoken_deliveredoneverycall_toverifycallorigin",
    "secret":     "this_isOnly32charsUsedfordecrypt"
}

Your Endpoint (POST)

This is the way your endpoint is called with the actual webhook information.
Please see Data Examples for detailed information.

Delete a Registration

To delete a registration to an event, call following endpoint with the according event name.
DELETE https://rest.cleverreach.com/hooks/eventhook/{eventname}
This deletes all registration for the event.

To delete a registration with a specific condition, add another parameter:
DELETE https://rest.cleverreach.com/hooks/eventhook/{eventname}/{condition}

The response is a simple 200 or a 404 nothing to delete if there was nothing to delete.

List Registrations

To get a list of all registered events, call:
GET https://rest.cleverreach.com/hooks/eventhook

Example response:

[
    {
        "url":       "https://hook.waynecorp.gc/cleverreach",
        "condition": "1939",
        "event":     "receiver",
        "oauth_app": "7h384tm4n1"
    },
    {
        "url":       "https://hook.waynecorp.gc/cleverreach",
        "condition": "1939",
        "event":     "form",
        "oauth_app": "7h384tm4n1"
    }
]

Data Examples

In case of an event in your CleverReach account your registered endpoint is called with specific information to inform you what happened.
For data protection reasons, explicit data is avoided to be transmitted. Instead IDs are used. For detailed information you can use IDs to request our REST API.

In some cases IDs are not useful. One example is the deletion of a receiver. You could not retreive the email, because the receiver was deleted already. Therefore the email is transferred, but encrypted.

See here some examples for registering and the webhook data to be expected.
Please note that the condition is optional!

Receiver

Register

This will register for all receiver events, limited to group/list "1939".

{
    "url":       "https://hook.waynecorp.gc/cleverreach",
    "event":     "receiver",
    "condition": "1939",
    "verify":    "damnSecretBatTokenForVerify"
}

The condition here is the groupd id (receiver list).

Event Data

Some receiver just subscribed to your list "1939".

{
    "event":      "receiver.subscribed",
    "condition":  "1939",
    "payload": {
        "pool_id":  "42",
        "group_id": "1939"
    }
}

Some receiver was deleted from your list "1939". Note the encrypted email address.

{
    "event":      "receiver.deleted",
    "condition":  "1939",
    "payload": {
        "pool_id":  "42",
        "email":    "encrypted3mail4ddressheret0bedecryptedw1ththegivensecret",
        "group_id": "1939"
    }
}

Form

Register

This will register for all form events, limited to group/list "1939".

{
    "url":       "https://hook.waynecorp.gc/cleverreach",
    "event":     "form",
    "condition": "1939",
    "verify":    "damnSecretBatTokenForVerify"
}

Event Data

Some form was updated in your CleverReach account.

{
    "event":     "form.updated",
    "condition": "1939",
    "payload": {
        "form_id": "23"
    }
}

Automation

Register

This will register for automation events of the collection "123456789". Note that the condition is optional!

{
    "url":       "https://hook.waynecorp.gc/cleverreach",
    "event":     "automation",
    "condition": "123456789",
    "verify":    "damnSecretBatTokenForVerify"
}

Event Data

Your automation collection "123456789" was activated.

{
    "event":           "automation.activated",
    "condition":       "123456789",
    "payload": {
        "collection_id": "123456789"
    }
}

Encrypted Information

For some events there is encrypted information included. The secret to decrypt that information is included in the response to a successful registration.
Algorithm used: aes-256-cbc. Example PHP code:

function decode($encrypted, $secret) {
    $enc_bin = hex2bin($encrypted);
    $key = hash('sha256', $secret, true);
    $iv = substr($enc_bin, 0, 16);
    $decoded = openssl_decrypt(substr($enc_bin, 16), 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);

    return $decoded;
}
©2022 CleverReach