> ## 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.

# Set up webhooks from your system

> Register your endpoint, choose its scopes and change them through the API, with the merchant's API key.

An integration can set up its own [webhooks](https://kb.paymentsmojo.com/developers/webhooks.md), so the merchant doesn't have to copy addresses
and keys between systems. The merchant only creates an API key for you.

Needs: an API key with `webhooks.manage` ("Set up webhooks" in the portal), plus read permissions for the records you'll
fetch, such as `payments.view`. Only a merchant's Owners and Admins can give a key `webhooks.manage`.

## Register your endpoint

`GET /webhooks/scopes` lists every scope, what makes it fire and where to read its record. Then register:

```bash theme={null}
curl https://api.paymentsmojo.com/webhooks \
  -H "Authorization: Bearer eyJ…" \
  -H "Idempotency-Key: ipaas-setup-7731" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "iPaaS.com",
        "url": "https://hooks.example.com/mojo",
        "enabled": true,
        "scopes": ["customer/created", "customer/updated", "invoice/created", "invoice/updated", "transaction/created"],
        "headers": [{ "name": "AuthKey", "value": "your-issued-key" }, { "name": "X-Company", "value": "north" }]
      }'
```

* Leave out `bodyTemplate` for the standard body, or send your own ([Your own body](https://kb.paymentsmojo.com/developers/webhooks.md#your-own-body)).
* The answer (`201 Created`) has the endpoint, with its `id`, and its `signingSecret`, shown only this once. Keep
  the `id`: it's how you change the endpoint later. Names don't have to be unique, so don't look endpoints up by name.
* With an `Idempotency-Key`, a retry from the same API key for the same `url` returns the same endpoint and secret
  with `200 OK` instead of making a second one ([Safe retries](https://kb.paymentsmojo.com/developers/idempotency.md)).
* Header values come back on `GET`, except credentials: a header named like a key, token, secret, password, signature
  or cookie (such as `AuthKey`), or one sent with `"secret": true`. Those show `"secret": true`, no `value`, and
  the last four characters of a long value (`valueLast4`).
* A merchant can have up to 10 endpoints.

## More than one environment

Each API key sees, changes and removes only the endpoints it registered. So two environments of your integration,
such as a production server and a staging server, each with its own API key from the merchant, register the same way
side by side: each gets its own endpoint, neither can touch the other's, and both are told about the same changes. The
merchant sees both in **Settings → Webhooks** and can turn either off on its own. Give each a name that says which it
is, such as `iPaaS.com` and `iPaaS.com (staging)`.

## Change it

`PATCH /webhooks/{id}` changes only what you send:

| Field | Does |
| - | - |
| `enabled` | `false` pauses it (notifications waiting are skipped); `true` starts it again |
| `addScopes`, `removeScopes` | Turn scopes on and off |
| `scopes` | Replace the whole list |
| `setHeaders` | Add or replace headers by name, as `[{ "name": "AuthKey", "value": "…" }]`; add `"secret": true` to hide a value that isn't named like a credential |
| `removeHeaders` | Header names to remove |
| `name`, `url` | Rename it, or move it |
| `bodyTemplate` | A new template; `""` goes back to the standard body |

```bash theme={null}
curl -X PATCH https://api.paymentsmojo.com/webhooks/9b1c0e52-… \
  -H "Authorization: Bearer eyJ…" -H "Content-Type: application/json" \
  -d '{ "addScopes": ["deposit/created"], "removeScopes": ["customer/updated"] }'
```

`PUT /webhooks/{id}` replaces everything at once instead: a header sent without a `value` keeps its stored value, and
headers left out are removed.

## Everything else

| Call | Does |
| - | - |
| `GET /webhooks` | The endpoints your API key registered, with the scope list, placeholders and the standard body |
| `GET /webhooks/{id}` | One endpoint, with how its deliveries are going |
| `POST /webhooks/{id}/test` | Sends a `webhook/test` notification now and returns what your endpoint answered |
| `GET /webhooks/{id}/deliveries` | The last 100 notifications: delivered, retrying, failed or skipped, with your endpoint's answer |
| `POST /webhooks/{id}/deliveries/{deliveryId}/retry` | Sends a failed or skipped notification again |
| `POST /webhooks/{id}/signing-secret` | A new signing secret (the old one stops working at once) |
| `DELETE /webhooks/{id}` | Removes the endpoint and its history |

## What the merchant sees

The merchant's **Settings → Webhooks** shows your endpoint as set up by your API key, and they can change, pause or
delete it. If they revoke the key, you can no longer change the endpoint, but it keeps sending until they turn it off
or delete it.


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