Step 3: Handle requests

The data is provided in a POST request that consists of an array of events. Each event is structured as an event object but its structure varies in accordance to the type of the event (see below for detailed descriptions for each type). Your endpoint should: check the authorization (in accordance to the setting in panel), save the payload, respond with

HTTP/1.1 200 OK

Your server should NOT validate the payload before giving the response. The only reasons to respond with something other than success should be authorization failure or an actual internal server error. You should parse your stored payload data into intended structures in a different process (than the receiving endpoint). The request timeout for webhooks is set to 500ms

Our request can look like this:

[{
  "externalId":"xxxxxxxxxxxxxxxxxxxxxxxx",
  "phoneNumber":"+48XXXXXXXXX",
  "status":1,
  "statusDesc":"DELIVERED",
  "statusTime":"2021-04-27T00:00:18",
  "webhookUrl":"xxxxxxxxxxxxxxx"
}]

or like this:

[{
  "externalId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "appId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "platform": 1,
  "status": 1,
  "statusDesc": "Accepted by push operator",
  "statusDetails": "NOTIFICATION_CLICK_ACTION",
  "statusTime": "2020-12-08T11:57:08",
  "actionId": null,
  "code":null
}]

The specific fields depend on the type of webhook (see below).

Authorization

Make sure that the webhooks actually come from us and stay secure. In the panel you can see 2 options for authentication:

• None

• Basic auth.

Whether you choose to additionally use basic auth or not, you should always check the hash of incoming webhook. With our POST request, in addition to the standard HTTP headers, we send three headers will allow you to verify if the data actually come from us:

Header	Type	Description
X-Webhook-Date	string	Date on which the webhook is sent
X-Webhook-Checksum	string	Checksum
Request-Id	string	Unique request ID

Now, the checksum is generated from a string built like this:

secretkey|X-Webhook-Date|Request-Id

Value	Description
secretkey	is a key given to you when you configure your webhook inside the panel
X-Webhook-Date	from headers
Request-Id	from headers

and SHA1 is used as hash functions.

Additionally, you can protect your script with basic auth. All you need to do is turn the option on and set login and password in the panel. Then, of course, add authentication to your endpoint.

Webhook types and event object structures

Transactional e-mails

Field	Type	Example
subject	string	Your chosen subject
smtpAccount	string	1.accountname.smtp
to	object
to[email]	string	[e-mail]
to[name]	string	Jane Doe
to[messageId]*	string	[e-mail]
from	object
from[email]	string	[e-mail]
from[name]	string	Test Corp.
tags	array | null	[tag1,tag2]
status	string	dropped
statusTime	int	1580996271
statusDesc	string	[e-mail] in blacklist
allStatuses	object[]
allStatuses[][status]	string	injected
allStatuses[][statusTime]	int	1580996275
allStatuses[][statusDesc]	string	injected

*Remember to use unique message_ids so that you can later aggregate all the webhooks (with consecutive statuses).

Values for field status:

ok
injected
hardbounce
softbounce
spambounce
dropped
deferred

example:

[
{
      "subject": "Your chosen subject",
      "smtpAccount": "1.accountname.smtp",
      "to": {
        "email": "[e-mail]",
        "name": "Jane Doe",
        "messageId": "[e-mail]"
      },
      "from": {
        "email": "[e-mail]",
        "name": "Test Corp."
      },
      "tags": null,
      "status": "dropped",
      "statusTime": 1580996271,
      "statusDesc": "[e-mail] in blacklist",
      "allStatuses": [
        {
          "status": "injected",
          "statusTime": 1580996275,
          "statusDesc": "injected"
        },
        {
          "status": "dropped",
          "statusTime": 1580996271,
          "statusDesc": "[e-mail] in blacklist"
        }
      ]
    }
]

Transactional SMS - delivery reports

Field	Type	Example
externalId	string	test123
status	int	1
statusDesc	string	DELIVERED
statusTime	string	2021-12-12T12:12:12
webhookUrl*	string	https://test.pl/test.aspx

*This object contains a webhookUrl field because, when sending transactional SMS it is possible to specify a webhook URL inside send request directly. In that case, both default URL and secondary URL configured in the panel will be ignored and the webhook will be sent to this, additionally specified, URL.

example:

[{
  "externalId":"xxxxxxxxxxxxxxxxxxxxxxxx",
  "phoneNumber":"+48XXXXXXXXX",
  "status":1,
  "statusDesc":"DELIVERED",
  "statusTime":"2021-04-27T00:00:18",
  "webhookUrl":"xxxxxxxxxxxxxxx"
}]

Transactional SMS - clicked link

Field	Type	Example
externalId	string	test123
url	string	http://www.test.pl/kontact/?place=menu
clickTime	string	2021-12-12T12:12:12
ip	string	111.222.11.22
userAgent	string	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/xxx.xx (KHTML, like Gecko) Chrome/xxx.xx.xxx.xx Safari/xxx.xx Google
webhookUrl*	string	https://test.pl/test.aspx

*This object contains a webhookUrl field because, when sending transactional SMS it is possible to specify a webhook URL inside send request directly. In that case, both default URL and secondary URL configured in the panel will be ignored and the webhook will be sent to this, additionally specified, URL.

2-way communication - Incoming SMS

Field	Type	Example
id	string	F2D21CA2-916E-4B92-B686-606231D9165F
phoneNumber	string	[phone]
message	string	Thank You
ndi	string	48111222333
statusTime	string	2021-11-15T12:25:32

Push messages - delivery reports

Field	Type	Example
externalId	string	xxxxxxxxxxxxxxxxxxxxxxxx
appId	string	xxxxxxxxxxxx
platform	int	1
status	int	1
statusDesc	string	Accepted by push operator
statusDetails	string	NOTIFICATION_CLICK_ACTION
actionId	int	1
code	string	null
statusTime	string	2021-11-15T12:25:32

Values for field platform:

1	IOS
2	ANDROID

Values for field status:

1	DISCARDED
2	SCHEDULED
3	SENT
4	FAILED
5	RECEIVED
6	REACTED_ON

Values for field statusDesc:

DISCARDED	"Push validation failed"
SCHEDULED	"Push accepted by push operator"
SENT	"Push accepted by FCM/APNS servers"
FAILED	"Push dropped by FCM/APNS"
RECEIVED	"Push received by device"
REACTED_ON	"User reacted on push"

Values for field statusDetails:

NOTIFICATION_CLICK_ACTION
NOTIFICATION_SWIPE_ACTION
DIALOG_DISSMISS_ACTION

example:

[{
  "externalId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "appId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "platform": 1,
  "status": 1,
  "statusDesc": "Accepted by push operator",
  "statusDetails": "NOTIFICATION_CLICK_ACTION",
  "statusTime": "2020-12-08T11:57:08",
  "actionId": null,
  "code":null
}]