Sign In

mesibo Real-time webhook

mesibo webhooks allow you to monitor your app and users in real-time by receiving events from the mesibo cloud or on-premise server as they happen.

You can select events you are interested in, such as offline messages, users coming online or going offline, on-premise server status, billing updates, etc. You also need to provide a URL in the mesibo console that will be invoked with POST data in real-time by mesibo when such events occur.

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

{
	"server": "mesibo",
	"id": 15,
	"v": 2,
	"aid": 1,
	"ts": 1609757524820,
	"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 the Backend API. See Setting up a webhook.

On receiving a webhook request, your web service can read the webhook payload, extract information about the events that caused the webhook to be fired, and take appropriate action. For example, send an offline message via email or SMS if the user was offline and a new message has arrived. Refer to the section on event types and payloads to understand how to process different events.

If you are using the mesibo cloud offering, bandwidth used by webhooks counts toward your 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.
  • HTTPS is required for mesibo cloud webhooks. mesibo cloud only invokes secure (HTTPS) webhook URLs with valid hostnames.
  • For mesibo on-premise deployments, you may configure an HTTP URL at your discretion (highly discouraged). However, HTTP webhooks will not receive mesibo cloud-initiated events such as on-premise monitoring or billing updates.
  • Your webhook must handle POST requests with a JSON body.
  • It must respond with HTTP status code 200.
  • Your webhook must validate the request signature for security. See Authenticating Webhooks.

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 POST requests
  2. Events for which you need mesibo to invoke the webhook, such as when users come online or go offline, when a message fails, 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

Important: mesibo cloud requires HTTPS URLs with valid hostnames. HTTP URLs are only supported for on-premise deployments and will not receive cloud-initiated events.

Events

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

You can select various events to be notified about via 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 fail, pruned messages, etc. If a message fails, mesibo will inform you about the reason for failure: Invalid destination, Message expired, No available storage (Bandwidth exceeded)
  • Push Notification Results - Notify about 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
  • Call - Notify about call events including call offers, answers, hangups, and call duration
  • On-Premise Server Monitoring - Notify when your on-premise server goes offline or becomes unreachable
  • User Unreachable - Notify when users cannot reach your on-premise server
  • Billing - Notify about billing events and credit usage

Now that you are familiar with webhook basics, we will explain the webhook payload structure sent by mesibo, followed by details on various events and their payloads.

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 mesibo-onpremise
  • v - Version. The current version is 2.
  • aid - The Application ID of your app for which the webhook was set up. Example: 6320
  • ts - The time at which mesibo fired the webhook (epoch time in milliseconds)
  • id - Incrementing ID for events with the same timestamp. For a given ts, id values are in sequential order (0, 1, 2, ...). This allows you to detect missing or out-of-order events.
  • events - An array of events that have occurred. Each event will have a type field to identify the type of event. See Events.

The webhook URL will also include a sig query parameter containing the SHA-256 signature for authentication. See Authenticating Webhooks.

Authenticating Webhooks

To ensure that webhook requests are legitimate and originate from mesibo, you must validate each request using the provided signature.

Signature Verification

mesibo computes a SHA-256 hash of the webhook payload and includes it as a query parameter sig in the webhook URL.

The signature is computed as:

sig = SHA256(json_payload + '-' + app_token)

Where:

  • json_payload is the complete JSON body of the POST request
  • app_token is your application token from the mesibo console
  • The two are concatenated with a - separator

Example verification in PHP:

<?php
// Get the signature from query parameter
$received_sig = $_GET['sig'];

// Get the raw POST body
$json_payload = file_get_contents('php://input');

// Your app token from mesibo console
$app_token = "YOUR_APP_TOKEN";

// Compute expected signature
$expected_sig = hash('sha256', $json_payload . '-' . $app_token);

// Verify signature
if ($received_sig !== $expected_sig) {
    http_response_code(403);
    die('Invalid signature');
}

// Signature is valid, process the webhook
// ...
?>

Example verification in Python:

import hashlib
from flask import request

# Get the signature from query parameter
received_sig = request.args.get('sig')

# Get the raw POST body
json_payload = request.get_data(as_text=True)

# Your app token from mesibo console
app_token = "YOUR_APP_TOKEN"

# Compute expected signature
expected_sig = hashlib.sha256((json_payload + '-' + app_token).encode()).hexdigest()

# Verify signature
if received_sig != expected_sig:
    return 'Invalid signature', 403

# Signature is valid, process the webhook
# ...

Example verification in Node.js:

const crypto = require('crypto');

// Get the signature from query parameter
const receivedSig = req.query.sig;

// Get the raw POST body (assuming body-parser or similar middleware)
const jsonPayload = JSON.stringify(req.body);

// Your app token from mesibo console
const appToken = "YOUR_APP_TOKEN";

// Compute expected signature
const expectedSig = crypto
    .createHash('sha256')
    .update(jsonPayload + '-' + appToken)
    .digest('hex');

// Verify signature
if (receivedSig !== expectedSig) {
    res.status(403).send('Invalid signature');
    return;
}

// Signature is valid, process the webhook
// ...

Additional Security Checks

In addition to signature verification, you should implement the following security measures:

  1. Timestamp validation - Check that the ts field is within an acceptable time window (e.g., within 5 minutes of current time) to prevent replay attacks:
const webhookTs = payload.ts;
const currentTs = Date.now();
const maxSkew = 5 * 60 * 1000; // 5 minutes in milliseconds

if (Math.abs(currentTs - webhookTs) > maxSkew) {
    console.error('Webhook timestamp too old or too far in future');
    res.status(403).send('Invalid timestamp');
    return;
}
  1. ID sequence validation - For a given ts, ensure that id values are in incrementing order. This helps detect missing or duplicate events:
// Store last seen ts and id for each application
// This is a simplified example - implement persistent storage in production
const lastSeen = {}; // { aid: { ts: timestamp, id: lastId } }

const aid = payload.aid;
const ts = payload.ts;
const id = payload.id;

if (lastSeen[aid]) {
    if (ts === lastSeen[aid].ts) {
        // Same timestamp - id should be incrementing
        if (id <= lastSeen[aid].id) {
            console.error('Out of order or duplicate event');
            // Handle accordingly
        }
    } 
}

// Update last seen
lastSeen[aid] = { ts, id };

Response for Cloud-Initiated Webhooks

For webhooks initiated by mesibo cloud, your webhook must respond with a JSON payload containing the result and signature:

{
    "result": true,
    "sig": "<signature>"
}

This allows mesibo cloud to continue sending webhooks. The signature should be computed using the same method as request validation.

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

Events

User

When users come online or go offline, a user event is fired. It contains information about the user and their status.


In the consoleopen_in_new, you can check the required option in User Status for the webhook to be fired when a user comes online, offline, or both.

A user event contains the following:

  • type - Always set to 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

Example webhook payload for a user event (when a user goes offline):

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

Message

When any message is sent in the app, a message event is fired. It contains information about the message, such as the message contents, sender and receiver, and message status (delivered, read, or failed). If the message failed, it includes the reason for failure.

In the consoleopen_in_new, you can check the required options in Messages and Message Status to configure which message events should trigger webhooks.

A message event contains the following:

  • type - Always set to 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
  • gid - Group ID (if message is sent to a group), otherwise 0
  • encoding - Set to base64 if the message is base64 encoded
  • message - The message object, containing one or more fields (maximum length of 512 bytes for cloud, unlimited for 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 a rich message
    • data - Base64 encoded binary message content, if the message is not a 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 field 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 exceeded the expiry duration
    • nostorage - Storage is disabled for user and user is offline

Example webhook payload for a message event (when a message has failed):

{
	"server": "mesibo",
	"id": 0,
	"v": 2,
	"aid": 1,
	"ts": 1609757523436,
	"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 service indicates an error, a push event is fired. It contains information about the failed push notification.

A push event contains the following:

  • type - Always set to push
  • device - android or ios
  • service - fcm if using Firebase Cloud Messaging (FCM) or apn if using Apple Push Notification (APN). Only present if the response code is from the actual push service
  • sent - Boolean indicating if the push was sent. Set to false if mesibo couldn't send the push
  • request - Information about the request sent by mesibo to your push service (FCM/APN):
    • sandbox - true if using a sandbox, false if 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):
    • 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:
    • 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, refer to the respective documentation of push notification error codes to understand the cause of failure:

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

Error CodeDescription
901Push service for the app is not configured
902Push service for the app is temporarily disabled
903Push certificate expired
904Push certificate error
905Production certificate is required for this push
911Bad push token
912Mismatch in APN certificate and the push token app id
913Bad payload

Example webhook payload for a push event:

{
	"server": "mesibo",
	"id": 2,
	"v": 2,
	"aid": 1,
	"ts": 1609757525000,
	"events": [{
		"type": "push",
		"device": "android",
		"service": "fcm",
		"to": {
			"uid": 23724,
			"address": "919999900140"
		},
		"request": {
			"body": "{\"to\":\"fcm_token_here\",\"notification\":{...}}"
		},
		"response": {
			"code": 400,
			"body": "{\"error\":\"InvalidRegistration\"}"
		}
	}]
}

Call

When call events occur (call offers, answers, hangups, etc.), a call event is fired. It contains information about the call, participants, and call status.

A call event contains the following:

  • type - Always set to call
  • to - The call destination user:
    • uid - The User ID of the destination
    • address - The address of the destination user
  • from - The call originator:
    • uid - The User ID of the caller
    • address - The address of the caller
  • id - Call ID
  • ts - Call timestamp (epoch in seconds)
  • duration - Call duration in seconds (only present for hangup events)
  • type - Call type: 0 for audio, 1 for video
  • status - Call status, can be one of:
    • offer - Call offer/initiation
    • answer - Call answered
    • hangup - Call ended
    • busy - Callee is busy
    • noanswer - No answer
    • cancelled - Call cancelled
    • unreachable - Callee unreachable

Example webhook payload for a call event (call hangup with duration):

{
	"server": "mesibo",
	"id": 3,
	"v": 2,
	"aid": 1,
	"ts": 1609757526000,
	"events": [{
		"type": "call",
		"status": "hangup",
		"id": 12345,
		"ts": 1609757400,
		"duration": 125,
		"type": 1,
		"from": {
			"uid": 237234,
			"address": "919999900139"
		},
		"to": {
			"uid": 23724,
			"address": "919999900140"
		}
	}]
}

OnPremise

When your mesibo on-premise server goes offline or comes back online, an onpremise event is fired. This allows you to monitor the health and availability of your on-premise deployment.

Note: This is a cloud-initiated webhook and will only be sent if your webhook URL is HTTPS. HTTP webhooks will not receive this event.

An onpremise event contains the following:

  • type - Always set to onpremise
  • online - Boolean: true if the on-premise server came online, false if it went offline
  • when - Time in seconds:
    • For offline events: Number of seconds the server was offline before the event was detected
    • For online events: Always 0

Example webhook payload for an onpremise event (server went offline):

{
	"server": "mesibo",
	"id": 0,
	"v": 2,
	"aid": 1,
	"ts": 1609757527000,
	"events": [{
		"type": "onpremise",
		"online": false,
		"when": 3600
	}]
}

Unreachable

When a user attempts to connect to your on-premise server but cannot reach it, an unreachable event is fired. This helps you identify connectivity issues from specific users or networks.

Note: This is a cloud-initiated webhook and will only be sent if your webhook URL is HTTPS. HTTP webhooks will not receive this event.

An unreachable event contains the following:

  • type - Always set to unreachable
  • uid - User ID of the user who could not reach the on-premise server
  • ip - IP address of the user attempting to connect

Example webhook payload for an unreachable event:

{
	"server": "mesibo",
	"id": 2,
	"v": 2,
	"aid": 1,
	"ts": 1609757528000,
	"events": [{
		"type": "unreachable",
		"uid": 23724,
		"ip": "1.2.3.4"
	}]
}

Billing

When billing events occur or credit usage thresholds are reached, a billing event is fired. This allows you to monitor your application's credit consumption.

Note: This is a cloud-initiated webhook and will only be sent if your webhook URL is HTTPS. HTTP webhooks will not receive this event.

A billing event contains the following:

  • type - Always set to billing
  • credits - Number of credits consumed or remaining
  • when - Time in seconds since the billing event occurred (0 for current events)

Example webhook payload for a billing event:

{
	"server": "mesibo",
	"id": 3,
	"v": 2,
	"aid": 1,
	"ts": 1609757529000,
	"events": [{
		"type": "billing",
		"credits": 1000.50,
		"when": 0
	}]
}

Debugging Webhooks

Ensure that your webhook is responding to POST requests and is accessible from outside your network. Use online tools like https://www.site24x7.com/check-website-availability.htmlopen_in_new to verify that your webhook is reachable and responding correctly.

Debugging checklist:

  1. Verify HTTPS setup - mesibo cloud requires HTTPS. Ensure your SSL certificate is valid
  2. Check signature validation - Ensure you're correctly computing and validating the SHA-256 signature
  3. Validate timestamp - Check that your server's clock is synchronized and you're accepting webhooks within a reasonable time window
  4. Monitor ID sequence - Track the id field to ensure events are processed in order and none are missed
  5. Return HTTP 200 - Your webhook must return status code 200 for successful processing
  6. Check console configuration - Verify that you have configured the correct parameters in the Webhook section of the consoleopen_in_new
  7. Review error responses - If webhooks are being disabled, check your response codes and ensure you're not timing out
  8. Test locally first - Use tools like ngrok to expose a local webhook endpoint for testing before deploying to production

Common issues:

  • Webhooks stop being sent - If your webhook repeatedly fails or times out, mesibo will temporarily disable it. Ensure your webhook responds quickly (within 5 seconds) and returns HTTP 200
  • Invalid signature errors - Verify that you're using the correct app token and computing the signature over the raw JSON body, not a parsed/reformatted version
  • Missing events - Check the id field for gaps. If you detect missing events, it could indicate network issues or webhook processing failures
  • Timestamp validation failures - Ensure your server's clock is synchronized with NTP. Allow for reasonable clock skew (e.g., ±5 minutes)

Best Practices

  1. Process asynchronously - Don't perform time-consuming operations in your webhook handler. Queue the event for background processing and return HTTP 200 immediately
  2. Implement idempotency - Use the combination of aid, ts, and id to detect and handle duplicate webhook deliveries
  3. Monitor webhook health - Track webhook success rates, processing times, and error patterns
  4. Use persistent storage - Store the last processed ts and id for each application to detect gaps or replay attacks
  5. Validate all inputs - Don't trust webhook data blindly. Validate event types, user IDs, and message content
  6. Handle errors gracefully - If processing fails, log the error and still return HTTP 200 to prevent webhook disabling
  7. Keep secrets secure - Never log or expose your app token. Store it securely using environment variables or secret management systems
  8. Test thoroughly - Test your webhook with all event types before going to production
  9. Scale appropriately - Design your webhook endpoint to handle high volumes if you have many active users
  10. Use HTTPS always - Even for on-premise deployments, HTTPS is strongly recommended for security

Migration from v1 to v2

If you're upgrading from webhook v1, here are the key changes:

  1. Version field - v is now 2 (was 1)
  2. No more secret field - The secret field has been removed. Use signature validation instead
  3. Signature-based authentication - Authenticate webhooks using the sig query parameter with SHA-256 hash
  4. ID field semantics - The id field now increments for events with the same timestamp, providing ordering guarantees
  5. Timestamp precision - ts continues to be epoch time in milliseconds
  6. Content-Type - Only application/json is supported. application/x-www-form-urlencoded is no longer supported
  7. HTTPS requirement - mesibo cloud now requires HTTPS webhooks. HTTP is only supported for on-premise deployments
  8. New event types - Added onpremise, unreachable, and billing events
  9. Cloud webhook responses - Cloud-initiated webhooks require a JSON response with result and sig fields
  10. Message field limits - Message content is limited to 512 bytes for cloud (was 256 bytes), unlimited for on-premise

Migration steps:

  1. Update your webhook endpoint to validate signatures instead of the secret field
  2. Implement timestamp and ID sequence validation
  3. Ensure your webhook URL uses HTTPS
  4. Update to expect v: 2 in webhook payloads
  5. Handle new event types (onpremise, unreachable, billing) if relevant
  6. Remove any code that expects or sends application/x-www-form-urlencoded content
  7. For cloud-initiated webhooks, update your response to include the required JSON format
  8. Test thoroughly with both cloud and on-premise deployments if applicable