Webhooks

Webhooks are HTTP POST requests that Monato sends to your endpoint when something happens, such as money arriving, a charge result or a cash operation being paid. Each product runs its own webhooks. Setup, security, the expected response and retries all differ, so check the table for your product.

Compare products

	Fincore	Direct Debit	Cash
Set up	API: `POST /v1/clients/{clientId}/webhooks`, one per `webhook_type`	Portal: Settings → Webhooks	API: `POST /api/v1/cash/webhooks`
How to check it is Monato	A `token` secret you set when you create the webhook, plus an `auth_type` (`AUTH`, `NO_AUTH`, `OAUTH`)	A header name and value you set in the Portal	`X-Webhook-Signature` (HMAC-SHA256) and `X-Webhook-Timestamp`, signed with the `secret_token` returned at setup
Your success response	`200`, `201` or `202` within 5 seconds	`200`, `201`, `202` or `204` within 5 seconds	`2xx` to activate the webhook
Retries	Not documented	Once per hour for up to 10 hours (10 retries)	Not documented
Events	Fincore webhook events	Direct Debit webhook events	Cash webhook events

Fincore

Create one webhook configuration per event type with Create webhook configuration. Send your client_id, your HTTPS url, a token, the webhook_type and the auth_type. The event types are MONEY_IN, STATUS_UPDATE, CEP, REPORT and REFUND.

The token is a secret that Monato sends in webhook delivery requests. Use a random value of at least 32 bytes.

Return your HTTP response within 5 seconds. Do the checks you need to accept or reject the event within that window, persist the event, then do the rest of the work asynchronously.

Your response	Meaning
`200`, `201`, `202`	Event received.
`422`	Event received but rejected by your business rules. For an external SPEI Money In, this starts a refund.

Use the message identifier to deduplicate events. Do not rely on delivery order.

Direct Debit

Configure your endpoint URL and a header name and value in the Monato Portal under Settings → Webhooks. Monato sends that header on every delivery, so compare it to check the request came from Monato.

Your endpoint must accept POST requests with a JSON body, be reachable from the public internet and return 200, 201, 202 or 204 within 5 seconds. Return the response before you process the event, because slow handlers increase the risk of timeout retries.

If the delivery fails, Monato retries once per hour for up to 10 hours. After the last retry the event is not sent again, so query the API for the current state.

Every event has the same top-level fields: event, timestamp (UTC) and data.

Cash

Register your URL with POST /api/v1/cash/webhooks. The response includes a secret_token. Only one webhook can be enabled per client at a time.

Monato then sends a webhook.activation test event to your endpoint. The webhook is activated only if your endpoint returns 2xx. After that, you get an event when an operation is paid, expires or is reversed. These events are sent only for closed references.

Each delivery includes X-Webhook-Timestamp and X-Webhook-Signature. Verify the HMAC-SHA256 signature with your secret_token before you trust the event.

Good practice

These points come from the product guides above:

Keep webhook secrets out of logs and frontend code.
Check the signature or Authorization value on every request before you trust it.
Respond quickly and move slow work out of the request.
Store event and transaction IDs so you can deduplicate and reconcile.
If deliveries stop, query the API for the current state of the resource.