> ## Documentation Index
> Fetch the complete documentation index at: https://kb.paymentsmojo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Be told the moment a customer, saved card, invoice, card transaction, recurring plan, deposit or location changes.

A webhook tells your system that something changed in Mojo Payments, as it happens, so you don't have to keep asking.
Each notification names the record and what happened to it. Your system then reads the record through the API, so it
always gets the current version, even from a late or repeated notification.

Integrations via iPaaS.com as a partner use webhooks this way. Any other system can too.

## Set one up in the portal

Owners and Admins do this in **Settings → Webhooks** (under **Developers**).

1. Select **Set up for iPaaS.com**, or **Add another endpoint** for any other system.
2. Enter the **URL** your system gave you. Webhooks are sent over https only, to public addresses.
3. Add any **Headers** your system needs, such as the **AuthKey** iPaaS.com issues. Values are kept encrypted. A
   credential is never shown again, only the last four characters of a long one: any header named like a key, token,
   secret, password, signature or cookie (such as **AuthKey**), or one you tick **Secret** for. Other values stay
   visible, so you can check and change them.
4. Under **What it hears about**, tick the scopes it needs, or **Everything**.
5. Leave the **Body** as **Standard**, or write your own template (below).
6. Select **Create webhook**. If your system checks signatures, copy the signing secret now: it's shown only once.

![The Webhooks page: an iPaaS.com endpoint that's on, with its history of delivered notifications, and a second endpoint that's off.](https://mintcdn.com/mojo-payments/GtTn_AJMJKfO3cM9/images/portal/webhooks.png?fit=max\&auto=format\&n=GtTn_AJMJKfO3cM9\&q=85\&s=a357953490ff13432119493ac51b556c)

Settings → Webhooks, an endpoint's history open (portal as of October 2026)

![The new webhook form: name, URL, an AuthKey header, every scope ticked, and the standard body.](https://mintcdn.com/mojo-payments/GtTn_AJMJKfO3cM9/images/portal/webhooks-ipaas.png?fit=max\&auto=format\&n=GtTn_AJMJKfO3cM9\&q=85\&s=dcc4414772b39694dac798cec658aefb)

Setting up a webhook for iPaaS.com (portal as of October 2026)

Each endpoint has **Send test**, a **History** of the last 30 days with **Send again** for anything that failed, and
**New signing secret**. Turn it off with the **On** box to pause it; notifications waiting to be sent are then skipped.

Your system can also set itself up with an API key instead: see [Set up webhooks from your system](https://kb.paymentsmojo.com/developers/webhooks-api.md).

## What a notification looks like

Mojo Payments sends a `POST` with a JSON body:

```json theme={null}
{
  "id": "1042",
  "scope": "invoice/updated",
  "external_id": "3f2c8a9e-6d1b-4c55-9a7e-2b8f0d4e1c77",
  "occurred_at": "2026-10-08T15:04:05.123Z",
  "organization_id": "6b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e"
}
```

| Field | Is |
| - | - |
| `scope` | What happened: the kind of record, a slash, and `created`, `updated` or `deleted` |
| `external_id` | The record's id: read it with the call for its scope (below) |
| `id` | This notification's own id. A retry repeats it, so you can drop duplicates |
| `occurred_at` | When it happened (UTC) |
| `organization_id` | Your Mojo Payments organization |

These headers come with every notification, with any headers of your own:

| Header | Value |
| - | - |
| `Mojo-Webhook-Scope` | The scope, the same as in the body |
| `Mojo-Webhook-Id` | The notification's id |
| `Mojo-Webhook-Timestamp` | When it was sent, in Unix seconds |
| `Mojo-Webhook-Signature` | `v1=` and the signature (below) |

Answer with any `2xx` status within 15 seconds. Anything else, or no answer, is tried again after 1, 2, 4 and more
minutes, then every 6 hours, 12 times in all (about a day). After that it shows as failed in the endpoint's
**History**, where you can send it again. Redirects aren't followed: use the final address.

## Scopes

| Scope | Sent when | Read the record with |
| - | - | - |
| `customer/created` | A customer is added: the first invoice or recurring plan for a new email address | `GET /customers/{id}` |
| `customer/updated` | A customer's name, company, phone or delivery choice changes | `GET /customers/{id}` |
| `customerProfile/created` | A customer's card is saved (a customer profile token at the processor) | `GET /saved-cards/{id}` |
| `customerProfile/deleted` | A saved card is removed, or replaced by saving the same card again | `GET /saved-cards/{id}` |
| `invoice/created` | An invoice is created | `GET /payment-requests/{id}` |
| `invoice/updated` | An invoice is sent, paid in part or in full, cancelled, or needs checking | `GET /payment-requests/{id}` |
| `transaction/created` | An authorization (a sale) or a refund through the POS Gateway is approved | `GET /pos-gateway/transactions/{id}` |
| `transaction/updated` | An approved authorization is captured or voided. The id is the authorization's | `GET /pos-gateway/transactions/{id}` |
| `cardTransaction/created` | A sale is captured, or a refund made, on one of your MIDs, however it was made: an invoice, a recurring charge, the POS Gateway, or outside Mojo Payments (those arrive when the processor pays them out) | `GET /card-transactions/{id}` |
| `cardTransaction/updated` | A card transaction is voided, or paid out in a deposit | `GET /card-transactions/{id}` |
| `recurringPlan/created` | A recurring plan is created | `GET /recurring-plans/{id}` |
| `recurringPlan/updated` | A plan is authorized, charged (approved or declined), paused, resumed, cancelled or completed | `GET /recurring-plans/{id}` |
| `campaignOrder/paid` | An order from a campaign page is paid in full | `GET /campaign-orders/{id}` |
| `deposit/created` | A deposit to your bank first appears | `GET /deposits/{id}` |
| `deposit/updated` | A deposit's amounts change, or a payment newly appears in it | `GET /deposits/{id}` |
| `location/created` | A location is added | `GET /locations/{id}` |
| `location/updated` | A location's name, address, time zone or status changes | `GET /locations/{id}` |
| `webhook/test` | Only when you select **Send test** (`external_id` is `test`) | |

A payment on an invoice is part of the invoice, so it's sent as `invoice/updated`; it's also a card transaction, so
`cardTransaction/created` follows within a minute. Declined card transactions and authorizations that are never
captured aren't sent. See [Card transactions](https://kb.paymentsmojo.com/developers/card-transactions.md). Reading a record needs an API key with the matching permission, such as `payments.view`
([Authentication](https://kb.paymentsmojo.com/developers/authentication.md)).

## Your own body

For a system that expects another shape, choose **My own template** and write the JSON it wants. These placeholders
are filled in, JSON-escaped, so put quotes around them yourself:

| Placeholder | Is |
| - | - |
| `{{scope}}` | The scope, such as `invoice/updated` |
| `{{external_id}}` | The record's id (required) |
| `{{object}}` | The part of the scope before the slash, such as `invoice` |
| `{{action}}` | The part after it: `created`, `updated` or `deleted` |
| `{{id}}` | The notification's id |
| `{{occurred_at}}` | When it happened |
| `{{organization_id}}` | Your organization's id |

For example, a list of notifications:

```json theme={null}
{ "notifications": [ { "scope": "{{scope}}", "external_id": "{{external_id}}" } ] }
```

## Check the signature

If your system checks where a notification came from, compute an HMAC-SHA256 of the `Mojo-Webhook-Timestamp` header,
a dot and the raw body, keyed with the endpoint's signing secret (`whsec_…`). Compare it, as lowercase hex, with what
follows `v1=` in `Mojo-Webhook-Signature`, and ignore notifications more than a few minutes old.

```js theme={null}
import crypto from 'node:crypto'

function isFromMojo(secret, timestamp, rawBody, signatureHeader) {
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}
```

**New signing secret** replaces the secret at once; update your system straight after.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.