Mesibo Real-time webhooks

Webhooks allow you to monitor your app and users in real-time by getting updates from the mesibo cloud or on-premise server, as it happens.

You can select events you are interested in, say, for example, an offline message, a user comes online, goes offline, billings, etc. You also need to provide an URL in the mesibo console that will be invoked with POST data in real-time by Mesibo when such events happen.

A typical webhook payload, in the POST request sent by mesibo to your web service, looks like below:

{
	"server": "mesibo",
	"id": 0,
	"v": 1,
	"aid": 1,
	"ts": 1609757524820,
	"secret": "some_secret_value",
	"events": [{
		"type": "user",
		"user": {
			"uid": 237234,
			"address": "919999900139"
		},
		"status": "offline"
	}]
}

In the above example, mesibo informs you of a user event — a certain user has gone offline. For mesibo to send such webhook requests, to notify you of various events, you need to set up webhooks for your app in the console or using Backend API. See Setting up a webhook.

On receiving a webhook request, your web service can read the webhook payload, get information about the events that caused the webhook to be fired, and take action. For example, send a push notification if the user was offline and a new message has arrived for the user. Refer to the section on event types and payloads to know about processing events.

If you are using the mesibo cloud offering, bandwidth used by Webhook counts towards the Real-time Bandwidth quota. You have an unlimited quota if you are using mesibo On-Premiseopen_in_new. See pricingopen_in_new for more details.

Webhook Requirements

The following requirements must be met by your webhook:

• Your webhook URL must be publicly accessible.
• It must handle POST requests with the JSON body.
• It must respond with a plain text message 'MESIBO OK'.

Setting up a Webhook

To configure webhooks in the consoleopen_in_new, go to your App Settings, click on Webhook. Turn ON the switch to enable webhooks and configure the following:

1. Webhook URL to which mesibo will send a POST request
2. Secret Token for the webhook to validate POST data
3. Content Type of the webhook payload. It can be application/json(default) or application/x-www-form-urlencoded
4. Events for which you need mesibo to invoke the webhook . For example, when users come online or go offline when a message failed, etc

We will now go through each of these settings in detail below.

Webhook URL

The webhook URL is the URL of the server that will receive webhook POST requests from mesibo.

For example,

https://example.com/webhook.php

Secret Token

Setting a secret token validates the POST requests. Your web service can ensure that requests from mesibo are legitimate if the request is received with a valid secret token.

Content Type

The webhook payload is JSON and delivered in the body of the POST request using the content-types application/json.

Events

Webhooks can be fired for various events happening in your mesibo app such as, when a user is offline, message failed, etc.

You can select various events to be alerted by mesibo using webhooks.

• User Status, Notify when users come online or go offline
• Message, Notify about new messages when the user is online or offline, when messages failed, pruned messages, etc. If the message failed, then mesibo will inform you about the reason for failure - Invalid destination, Message expired, No available storage(Bandwidth exceeded).
• Push Notification Results, Notify failed push notifications. You can debug push notifications sent by mesibo to your application by inspecting the push request and response, which will be made available to you through this webhook.
• On-Premise server monitoring
• Billing

Now that you are familiar with webhook basics, we will now explain the webhook payload structure sent by mesibo. We will then explain the various events and the contents of the webhook payload for each event so that you can handle the request appropriately on your web server.

Webhook Payload

A webhook payload sent by mesibo has the following structure:

• server, If sent by mesibo cloud, it is set to mesibo. If you are using mesibo on-premise, it will be the hostname of your on-premise server.
• v, Version, the current version is 1.
• aid, The Application ID of your app for which the webhook was setup. Example, 6320.
• ts, The time at which mesibo fired the webhook (epoch, in milliseconds)
• secret, The secret token that was configured by you in the console. See Secret Token
• events, An array of events that have occurred. Each event will have a type field to identify the type of event. See Events.

We will now explain various event types and their properties in detail.

User

When users come online or go offline, we have a user event. It will contain information about the user and their status.

A user event will contain the following:

• type, type will be user
• user, an object containing
  • uid, The User ID. For Example, 23724
  • address, The address of the user.
• status, offline if the user went offline, online if the user just came online.

A webhook payload sent by mesibo for a user event (when a user goes offline) looks like below.

{
	"server": "mesibo",
	"id": 0,
	"v": 1,
	"aid": 1,
	"ts": 1609757524820,
	"secret": "ds5678",
	"events": [{
		"type": "user",
		"user": {
			"uid": 237234,
			"address": "919999900139"
		},
		"status": "offline"
	}]
}

Message

When any message is sent on the app, we have a message event. It will contain information about the message, such as the message contents, the sender and receiver of the message, and the message status, whether delivered, read, or failed. If the message failed, it would contain the reason for failure.

In the consoleopen_in_new, you can check the required options in Messages and Message Status, for which you need the webhooks to be fired.

A message event will contain the following:

• type, message
• to, The message destination, containing
  • uid, The User ID of the destination. For Example, 23724. Zero if the message failed due to an invalid destination.
  • address, The address of the destination user.
• from, The message sender, containing
  • uid, The User ID of the sender. For Example, 23723
  • address, The address of the sender.
• mid, 64-bit Message ID
• encoding, sets to 'base64' if the message is base64 encoded.
• message, the message object, containing one or more fields (Maximum length of 256 bytes. Unlimited length if you are using mesibo on-premise)
  • "title, title of the rich message
  • "subtitle, subtitle of the rich message
  • "message, message content of the rich message
  • "url, media/file URL of the rich message
  • "text, message content, if the message is not the rich message
  • "data, base64 encoded binary message content, if the message is not the rich message
  • other fields, other custom message fields (on-premise only)
• status, Can be one of
  • delivered, If mesibo successfully delivered the message to the destination
  • read, If the recipient read the message
  • failed, If the message failed to be sent. In this case, the reason for failure will be present.
• reason, Reason why a message failed. Can be one of
  • invaliddest, The message was sent to an invalid destination. Check the destination address and ensure it is a valid mesibo user's address.
  • expired, The message has expired. You may have set an expiry value while sending the message, and the current time has crossed the expiry duration.
  • nostorage, storage is disabled for user and user is offline.

A webhook payload sent by mesibo for a message event (when a message has failed) looks like below.

{
	"server": "mesibo",
	"id": 0,
	"v": 1,
	"aid": 1,
	"ts": 1609757523436,
	"secret": "ds5678",
	"events": [{
		"type": "message",
		"status": "failed",
		"reason": "invaliddest",
		"to": {
			"uid": 0,
			"address": "xxx91974030501"
		},
		"from": {
			"uid": 237234,
			"address": "919999900139"
		},
		"mid": 1018913481048575,
        "message": {
            "title": "message title",
            "subtitle": "message subtitle",
            "message": "message content",
            "url": "https://mesibo.com"
        }
	}]
}

Push

When mesibo sends a push notification to FCM or APN on behalf of your application, and the FCM/APN indicates an error, we have a push event. It will contain information about the failed push message.

A push event will contain the following:

• type, push
• device, android or ios
• service, FCM if using Firebase Cloud Messaging(FCM) or APN if using Apple Push Notification(APN)
• request, Information about the request sent by mesibo to your push service(FCM/APN) containing
  • sandbox, true if using a sandbox, false if you are using a production server. (iOS only)
  • body, The complete request body with the push token, etc.
• response, Information about the response received by mesibo from the push service(FCM/APN) containing,
  • code, Response code indicating the result of the push request. For Example, 400
  • body, The complete response
• to, The user to whom the push notification was sent to
  • uid, The User ID. For Example, 23724
  • address, The address of the user.

The response.code field contains the error code which indicates the reason for failure.

If FCM/APN rejected the push, then refer to respective documentation of push notification error codes to understand the cause of failure.

• For FCM, refer hereopen_in_new
• For APN, refer hereopen_in_new

If Mesibo rejected the push, then the error code will be a value greater than 900. Refer to the table below for special error codes and their meaning:

Debugging Webhooks

Ensure that your webhook is responding to GET and POST requests outside your network. Use online tools like https://www.site24x7.com/check-website-availability.htmlopen_in_new to check if your webhook is reachable and outputting “OK”.

Check if you have configured the right parameters in the Webhook section in the consoleopen_in_new