Document Categories

Webhooks

Usermost webhooks let you add an HTTP callback to the events happening in Usermost. By configuring a webhook, Usermost is triggered to call a script on your web-servers whenever a particular event, for which you want to get real-time data, occurs and use it for internal purposes. You can use webhooks to send information to systems. You can also use webhooks to send information to your backend systems. For example, you might want to credit your customers’ accounts with promotion credits once they’ve performed a custom event a certain number of times.

Webhook Requests

Webhook requests will be posted to a URL configured by you and in the format described below. 

Webhook request method will always be POST. There will be additional parameters that will be appended to the postURL.

Request Headers:

NameDescription
x-request-id:{HEX_STRING}Used to identify webhook POST requests uniquely to achieve events idempotency. {HEX_STRING} will be replaced by a unique, random hex string.

Request Parameters:

NameDescription
eventTypeNOTIFICATION_SENT or NOTIFICATION_STATUS_RECEIVED
licenseCodeYour Usermost license key
secretThis secret key is to be used to identify the webhook POST requests from Usermost. More about request verification below(Request Verification section).

Request Body:

The Request body will contain event-specific data and will vary based on the registered webhook.

Response:

Usermost will understand HTTP Status, of the response. Responses with HTTP Status 200 will be treated as successful posts, everything else will be logged as failed webhook posts.
See the section about error handling and retries below to understand what happens in case of failures.

Request Verification:

You will find Webhook Secret Key for your account in the Integrations > Webhooks section of Usermost dashboard. This secret key is to be used to identify the Webhook POST requests from Usermost to your servers. Usermost appends a parameter named secret in the postURL. Value of this parameter is the MD5 Hex of the combination of your Usermost license code and the Webhook Secret Key separated by `:`.

Webhook Configuration

You will be able to configure URLs for different events from the Integrations > Webhooks section of your Usermost dashboard. Following are the webhooks you can configure.

Below is an example of how the event data for NOTIFICATION-SENT event looks like

{
	"id": "fadab629-eea3-4637-964e-71d122267fb9",
	"notified": true,
	"notificationDate": "2020-03-03T13:50:00.000+0000",
	"sent": true,
	"messageId": "65971469603",
	"user": {
		"id": "abcdcf83-96da-41ff-9156-b5b634902c78",
		"userId": "12345"
	},
	"campaign": {
		"pushMethod": "SMS",
		"id": "dfa6697a-62c7-4671-88bf-edfe4f718234",
		"delayMinutes": 0,
		"journey": {
			"name": "One Time Test",
			"id": "efc8cf83-96da-41ff-9156-b5b634902c78"
		}
	}
}

Below is an example of how the event data for NOTIFICATION_STATUS_RECEIVED event looks like

{
	"id": "fadab629-eea3-4637-964e-71d122267fb9",
	"notified": true,
	"notificationDate": "2020-03-03T13:50:00.000+0000",
	"sent": true,
	"messageId": "65971469603",
	"user": {
	"id": "abcdcf83-96da-41ff-9156-b5b634902c78",
	"userId": "12345"
	},
	"campaign": {
		"pushMethod": "SMS",
		"id": "dfa6697a-62c7-4671-88bf-edfe4f718234",
		"delayMinutes": 0,
		"journey": {
		"name": "One Time Test",
		"id": "efc8cf83-96da-41ff-9156-b5b634902c78"
		}
	},
	"sentSubject": "test title",
	"sentMessage": "test message",
	"sentOnClickAction": "test action",
	"deliveryStatus": "DELIVERED"
}

456 reads

Table of Contents

Let’s schedule your personalized demo