Webhooks

Webhooks feature allows you to get a real-time stream of events sent to your HTTPS endpoint. Webhooks alert you about events that have just occurred - for instance, a user displayed an In-App campaign, or subscribed to push notifications.

Combined with our Export API, they are often used to:

Orchestrate multi-channel communications
Keep your user profile data in sync with Batch related events

Webhooks is a paid option and will be setup with the help of your Solutions Engineer. Please contact us if you are interested.

Overview

HTTPS requests sent to the endpoint by Batch:

will use the POST method/verb.
will contain a JSON data payload (Content-Type: application/json).
will be identified with User agent (User-Agent: Batch.com/1.0).
will be authenticated (see below).
will be sent at least once (depending on retries).

Requirements

Endpoint must use HTTPS (valid SSL certificate issued by a recognized authority).
Response time should be under 100 milliseconds (ms) and endpoint must be localized in the EU area.
Response body won't be handled by Batch. We are only expecting an HTTP 200 or 201 status code.
Endpoint should be able to deduplicate events based on their ID if uniqueness is required.

Authentication

Secret key

In order to authenticate with your endpoint, Batch will provide your Webhook Secret as the value of the X-Authorization header.

X-Authorization: BATCH_WEBHOOK_SECRET

OAuth2

Alternatively, if your endpoint supports an OAuth2 authentication, the header will pass the OAuth2 Access Token under the standard Authorization header:

Authorization: Bearer OAUTH2_ACCESS_TOKEN

You'll have to provide Batch with the full URL of your authorization endpoint, and a set of grant_type, client_id and client_secret credentials.

Retries

If your endpoint fails to return a 200 or 201 status code Batch will retry periodically using an exponential backoff.

Your endpoint might be disabled if we receive too many errors over a long period: if that happens a manual intervention is required to enable the endpoint.

Batching

Batch supports delivering more than one event in a single HTTP request. This is useful to increase the delivery throughput and reduce the load on your endpoints.

Batching can be configured with the following properties:

max size which is the maximum number of events that should be in a batch. A batch is guaranteed to never have more than this number of events however it can have less events.
max wait time which is the maximum amount of time to wait before the batch is sent regardless of its size.

For example if batching is enabled with a max size of 10 and a max wait time of 5s the following will happen:

the batch is sent as soon as 10 events are generated
the batch is sent after 5s even if less than 10 events are generated

Batching is disabled by default. If you decide to enable it you can choose values in the following ranges:

max size must be between 10 and 1000.
max wait time must be between 1s and 30s.

If you don't choose values Batch will use default values:

max size of 100.
max wait time of 5s.

Data payload

The body of the request will contain a valid JSON payload describing a message and a single event (or a batch of events).

Here is how a complete JSON payload for a single event looks like:

{
  // version of this message
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",

  // fields provided on every event
  "event_type": "push_campaign_sent",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",

  // related identifiers
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002"
  },

  // additional properties (optional)
  "properties": {}
}

A batch of events is composed of a number of single events in an array. The format of each event is the same as the example above.

Here is how a complete JSON payload for a batch of events looks like:

{
  // version of the batch
  "version": 1,

  "events":
  [
    {
      // version of this message
      "version": 1,
      "api_key": "5306192C3549E92B2633D782D8A37X",

      // fields provided on every event
      "event_type": "push_campaign_sent",
      "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
      "occurred_at": "2020-06-25T19:50:30",

      // related identifiers
      "ids": {
        "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
        "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
        "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002"
      },

      // additional properties (optional)
      "properties": {}
    },
    {
      ...
    }
  ]
}

Test events

When configuring your Webhook endpoint Batch can send test events which can help you test and validate your code.

The payload will have the same format as a normal event, other than its event_type which will always be prefixed with test_.

All data in a test event will be randomly generated so take care not to save it.

Event types

push_campaign_sent

Event generated for every Push notification sent in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_campaign_sent",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  }
}

push_campaign_open

Event generated for every Push notification opened in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_campaign_open",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  }
}

push_campaign_undelivered

Event generated for every Push notification not delivered in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_campaign_undelivered",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  },
  "properties": {
    "reason": "error",
    "error_code": "apns_invalid_token"
  }
}

Reasons:

uninstalled : installation's push token has been unregistered
error : an error has been returned by the push API (see error code)
capping_limit : installation has reached a capping rule
expired : notification reached TTL before delivery

push_transactional_sent

Event generated for every Push notification sent in a Transactional API request.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_transactional_sent",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "group_id": "new_friend_request",
    "transactional_token": "3f98fd8c-4f44-4b8c-8f53-bf25de639b5a"
  }
}

push_transactional_open

Event generated for every Push notification opened in a Transactional API request.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_transactional_open",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "group_id": "new_friend_request",
    "transactional_token": "3f98fd8c-4f44-4b8c-8f53-bf25de639b5a"
  }
}

push_transactional_undelivered

Event generated for every Push notification not delivered in a Transactional API request.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_transactional_undelivered",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "group_id": "new_friend_request",
    "transactional_token": "3f98fd8c-4f44-4b8c-8f53-bf25de639b5a"
  },
  "properties": {
    "reason": "error",
    "error_code": "apns_invalid_token"
  }
}

Reasons:

not_found : no installation could be found for the supplied ID
unreachable : no push token could be found for the supplied ID
uninstalled : installation's push token has been unregistered
error : an error has been returned by the push API (see error code)
capping_limit : installation has reached a capping rule
expired : notification reached TTL before delivery

in_app_campaign_displayed

Event generated for every In-app message displayed in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "in_app_campaign_displayed",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  }
}

in_app_campaign_clicked

Event generated for every In-app message clicked in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "in_app_campaign_clicked",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  },
  "properties": {
      "cta_action": "batch_deeplink"
  }
}

in_app_campaign_closed

Event generated for every In-app message closed in a campaign.

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "in_app_campaign_closed",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002",
    "campaign_token": "566acd78ebdafceadc8b6fac0eec72ba"
  }
}

push_reachability_change

Event generated whenever an installation's reachability status change (eg: opt-in, opt-out, uninstall the app etc.).

{
  "version": 1,
  "api_key": "5306192C3549E92B2633D782D8A37X",
  "event_type": "push_reachability_change",
  "event_id": "230ca290-b71d-11ea-8b8a-0242c0a8042a",
  "occurred_at": "2020-06-25T19:50:30",
  "ids": {
    "install_id": "D0153F35-6568-4DC7-9BBB-D1A498411637",
    "custom_id": "7d544a8b7512115fd0d2bee3ab3e",
    "advertising_id": "3b671754-07df-11eb-adc1-0242ac120002"
  },
  "properties": {
    "is_reachable": true,
    "is_optin": true,
    "has_custom_id": true
  }
}

Properties:

is_reachable : installation has a push token
is_optin : installation enabled Push notifications for the app
has_custom_id : installation is linked to a user profile

Documentation > API