Webhook guide

What the app POSTs to your webhook URL for every captured transaction, and the reply it expects back.

Last updated 21 October 2026.

On this page

Overview

Every time MFS Tool captures an SMS from an approved sender, it sends one JSON POST to the Webhook URL you set in Onboarding (or later in Settings → Webhook).

  • Built-in senders: the SMS is parsed on your phone and only the transaction fields are sent. The raw SMS text is never sent.
  • Custom senders you add yourself: the raw message is forwarded as-is.

Your receiver decides what to do with the data and tells the app whether it was accepted.

Request

POST <your Webhook URL>
Content-Type: application/json
X-BT4-Key: <the Key you configured in the app>
  • Method: always POST.
  • Auth: one shared-secret header, X-BT4-Key, set to the Key you entered in the app. Treat it as a bearer token and reject anything that doesn't match.
  • Body: JSON, UTF-8, one message per request (never batched).
  • Timeout: the app waits 20 seconds for a response before treating the attempt as failed and retrying later.

Built-in senders

The message is parsed on the device and only these fields are sent. Every field is always present.

FieldTypeNotes
senderstringProvider display name, exactly as listed under Supported providers (e.g. bKash, BRAC Bank). Route on this.
typestringPersonal, Agent, Merchant or Bank.
amountstringTransaction amount, thousands separators removed (e.g. 1030.00). "0" if the SMS format doesn't include it.
phone_numberstringCounterparty number, card or account as printed in the SMS (may be masked, or a name such as a bank). If the SMS has none (common for bank credit alerts), a random 8-character token.
refstring | nullReference or note, or null when the SMS carried none. Optional, safe to ignore.
balancestringResulting balance, separators removed. "0" if the SMS format doesn't include it.
transaction_idstringProvider transaction ID (TrxID / TxnID / TxID / Ref). If the SMS has none (common for bank credit alerts), a random 8-character token, generated once at capture so every retry carries the same value.
received_atstring (ISO-8601)When the device received the SMS. Local time, millisecond precision, no offset.

Example: a bKash transfer

{
  "sender": "bKash",
  "received_at": "2026-09-04T19:22:03.412",
  "type": "Personal",
  "amount": "30.00",
  "phone_number": "01946664890",
  "ref": null,
  "balance": "39.59",
  "transaction_id": "DHI9JYQ9DD"
}

Example: a bank credit alert with no ID or counterparty

{
  "sender": "EBL Bank",
  "received_at": "2026-10-21T11:05:47.090",
  "type": "Bank",
  "amount": "1700.00",
  "phone_number": "Q7K2M9XA",
  "ref": null,
  "balance": "30000.00",
  "transaction_id": "4HZP0C1T"
}

A built-in-sender SMS that matches no known transaction format (an OTP or a promo, for example) is ignored. Nothing is stored or sent, because the raw text must not leave the device.

Supported providers

The value in the first column is sent as sender. The second column lists the type values that provider can produce.

sendertype values
Mobile financial services
bKashPersonal, Merchant, Agent
NagadPersonal, Merchant, Agent
RocketPersonal, Merchant, Agent, Bank
UpayPersonal, Merchant, Agent
TapPersonal
CellfinPersonal, Merchant, Bank
OkWalletPersonal
mCashPersonal, Merchant, Agent
PathaoPayPersonal, Merchant
TallyPayMerchant
DgePayMerchant
Banks
AB BankMerchant
Al-Arafah BankMerchant, Bank
Bank AsiaMerchant
BRAC BankMerchant, Bank
City BankMerchant, Bank
Dhaka BankMerchant
EBL BankBank
IFIC BankBank
Janata BankMerchant
Midland BankBank
Mutual Trust BankBank
Prime BankBank
Pubali BankMerchant, Bank
UCB BankMerchant, Bank

Custom senders

Senders you add yourself have no parsing rules, so the raw message is forwarded as-is.

FieldTypeNotes
senderstringThe custom sender's display name.
addressstringRaw originating address. For a manual entry it is manual:<Provider>.
messagestringFull SMS text (whitespace collapsed to single spaces).
received_atstring (ISO-8601)When the device received the SMS.
{
  "sender": "MyBank",
  "received_at": "2026-09-04T19:22:03.412",
  "address": "MYBANK",
  "message": "Your account was credited BDT 500 ..."
}

Expected response

The app marks a message Succeed only when the response body explicitly reports success. Your receiver must return a JSON body with a status:

HTTP 200
Content-Type: application/json

{ "status": "success" }
Response bodyApp behaviour
{"status":"success"} (or {"success":true})Marked Succeed.
{"status":"failed"}, or any other status valueMarked Failed and retried.
No status, a non-JSON body, a timeout, or no responseMarked Failed and retried.
  • Pending vs Failed: if the app reaches your webhook and the response is not success, the message is marked Failed immediately. Only when your webhook can't be reached at all (timeout or no network) does it stay Pending and keep retrying.
  • A missing or empty body counts as Failed. You must return {"status":"success"}, even on HTTP 200.
  • The HTTP status code is not used on its own; the status field is what matters. Still, return 2xx with {"status":"success"}.
  • For a duplicate you already have, return {"status":"success"} so the app stops retrying it.

Retry schedule

If a message isn't accepted, the app retries with exponential backoff:

5s → 15s → 60s → 5m → 30m (capped, repeats at 30m)

After 10 attempts a message is marked Failed. It is not dropped:

  • it keeps retrying automatically on the capped ~30-minute cadence, and
  • tapping Sync in the app retries every undelivered message (pending and failed) immediately.

There is also a background sweep of undelivered messages roughly every 15 minutes, and a flush as soon as connectivity returns while the app is open.

Duplicates

The app can send the same message more than once: its own retries and a periodic catch-up re-read of the SMS inbox can both attempt the same row.

  • Treat transaction_id as the unique key for built-in senders, and (address, message) for custom senders.
  • Accept a duplicate silently with {"status":"success"} (or return 409).
  • The app also de-duplicates on (address, message) locally, so repeats are rare.

When transaction_id is a generated token (the SMS printed none), it stays the same across every retry of that message, but it is not the provider's own ID. The app never re-imports inbox history from before it was installed, so an old SMS is not captured a second time with a new token.

Example receiver (PHP)

A minimal endpoint that checks the Key, accepts both payload shapes and replies in the format the app expects.

<?php
header('Content-Type: application/json');

$expected = 'YOUR_KEY';   // the Key you entered in the app
$key = $_SERVER['HTTP_X_BT4_KEY'] ?? '';
if (!hash_equals($expected, $key)) {
    http_response_code(401);
    echo json_encode(['status' => 'failed']);
    exit;
}

$data = json_decode(file_get_contents('php://input'), true);
if (!is_array($data) || !isset($data['sender'])) {
    http_response_code(400);
    echo json_encode(['status' => 'failed']);
    exit;
}

if (isset($data['transaction_id'])) {
    // Built-in sender: sender, type, amount, phone_number, ref, balance,
    // transaction_id, received_at. Store it, ignoring a duplicate transaction_id.
} else {
    // Custom sender: sender, address, message, received_at.
}

echo json_encode(['status' => 'success']);

What is not sent

Sender and pattern configuration (which senders the app listens to, and the rules that parse built-in senders) stays on the device and never leaves the phone. For built-in senders your receiver never sees the raw SMS text, only the parsed fields above. The parsing patterns are stored encoded inside the app, not in plaintext. See the Privacy Policy for the full picture.