Webhooks

Webhooks is an easy way of integrating your existing systems with Ubivox. Webhooks are just a single HTTP POST request sent for every specific event type.

Request structure

Webhook messages are sent as HTTP POST requests to the URL specificed. Messages are sent asynchronously to the trigger event, and may be delayed. Messages may not arrive in order. All messages consists of the following HTTP POST variables:

  • time - Local time when the event occurred. E.g.: 2009-12-31T23:59:59
  • data - The JSON encoded contents of the message

Throttling

When dealing with large systems, the amount of webhook calls may slow your systems down. Ubivox deals with this by allowing you to set a throttle parameter for each webhook. This defines a maximum numbers of webhook messages per minute for the particular webhook Ubivox will try to deliver.

Delivery guarantee

In order to make sure that each message arrives securely at the recieving server, we monitor the HTTP status codes in the replies. If we are given anything else than a 2xx reply, we will retry the current message later. Messages are retried at an interval of at least five minutes until the retry limit has been hit.

Setting up

Webhooks are setup through the Ubivox interface by choosing Account then Webhooks in the top menu.

Supported webhooks

We currently support webhooks for the following events:

subscription

Subscription event

{
    "address": "example@example.org",
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

updated_email

Updated e-mail address

{
    "new_address": "new-example@example.org",
    "old_address": "old-example@example.org"
}

unsubscription

Unsubscription event (by subscriber request)

{
    "address": "example@example.org",
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

remove_subscription

Unsubscription event (by administrator)

{
    "address": "example@example.org",
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

suspend_subscription

Suspend event (due to delivery failure)

{
    "address": "example@example.org",
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

activate_subscription

Reactivation of a suspended subscription

{
    "address": "example@example.org",
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

login

Login event (in the administrative interface)

{
    "from": "208.77.188.166",
    "username": "example"
}

junk_delivery

Junked delivery event

{
    "address": "example@example.org",
    "delivery_id": 10,
    "list": "Company Contacts",
    "list_id": 5,
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    }
}

junk_email

Junked e-mail event (from E-mail API)

{
    "reference": "..."
}

bounced_email

Bounced e-mail event (from E-mail API)

{
    "address": "example@example.org",
    "classification": "hard|soft",
    "reference": "..."
}

delivery_started

Delivery of a newsletter has started

{
    "delivery_id": 42,
    "delivery_subject": "My newsletter",
    "list": "Company Contacts",
    "list_id": 5
}

delivery_read

First read of a delivery by a subscriber

{
    "address": "example@example.org",
    "delivery_id": 42,
    "delivery_subject": "My newsletter",
    "event": "open",
    "list": "Company Contacts",
    "list_id": 5,
    "remote_addr": "198.51.100.60",
    "subscriber_data": {
        "City": "Springfield",
        "Firstname": "John",
        "Lastname": "Doe"
    },
    "user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"
}