Skip to content
/
Webhooks
Last updated

Webhooks

Webhooks notify your system about asynchronous events such as Money In, transaction status updates, CEP results, and report availability.

This guide includes the webhook configuration and event contracts.

Webhook flow

StepActionOpenAPI contract
1Configure a webhook URLCreate webhook configuration
2List configured webhooksList webhook configurations
3Retrieve one webhookRetrieve webhook configuration
4Update a webhookUpdate webhook configuration
5Delete a webhookDelete webhook configuration

Event contracts

EventUseOpenAPI contract
Money InIncoming SPEI or internal credit.Money In webhook event
Status updateMoney Out status changes.Status update webhook event
CEPPenny Validation result. Status values and transitions are documented in CEP Statuses.CEP webhook event
RefundA refund transaction was created.Refund webhook event
ReportGenerated report file available.Report webhook event

Delivery response expectations

Response timeout

Your endpoint must return its HTTP response within 5 seconds of receiving a webhook request. This maximum response time applies to Money In, status update, CEP, refund, and report webhooks.

Complete the validations required to accept or reject the event within this window. Before acknowledging acceptance, persist the event safely; then perform any remaining processing asynchronously. For external Money In, make the acceptance or rejection decision before responding, as described in the Money In guide.

Your responseMeaning
200, 201, 202Event received.
422Event received but rejected by your business validation. For external Money In, this can trigger refund behavior.

Security notes

Store webhook secrets securely. Do not expose them in logs or frontend code.

Validate the event type and message identifier before processing. Use the message identifier for deduplication.

API contracts

Create webhook configuration

Endpoint: POST /v1/clients/{clientId}/webhooks

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Path parameters

clientIdstring, (uuid)required

Client UUID for which the webhook is being registered.

Request body

client_idstring, (uuid)required

Client UUID that owns the webhook configuration.

Example:"c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring, (uri)required

Public HTTPS URL where Monato sends webhook events.

Example:"https://example.com/webhook"
tokenstringrequired

Secret sent by Monato in webhook delivery requests. Use a random value of at least 32 bytes.

Example:"secretToken0123"
webhook_typestringrequired

Type of event delivered to this webhook.

Enum:"MONEY_IN""STATUS_UPDATE""CEP""REPORT""REFUND"
Example:"MONEY_IN"
auth_typestringrequired

Authentication mode used when Monato delivers webhook events.

Enum:"AUTH""NO_AUTH""OAUTH"
Example:"AUTH"

Request example

Payload
{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhook_type": "MONEY_IN",
  "auth_type": "AUTH"
}

200 response body

idstring, (uuid)required

Webhook configuration UUID.

Example:"29806117-2b15-4682-87f0-350e6695fe91"
clientIdstring, (uuid)required

Client UUID that owns the webhook.

Example:"c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring, (uri)required

Destination URL where Monato sends webhook events.

Example:"https://example.com/webhook"
webhookTypestringrequired

Type of events delivered to this webhook.

Enum:"MONEY_IN""STATUS_UPDATE""CEP""REPORT""REFUND"
Example:"MONEY_IN"
webhookStatusstringrequired

Current webhook lifecycle status.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
tokenstring

Secret configured for webhook delivery.

Example:"secretToken0123"
createdAtstring, (date-time)

Timestamp when the webhook configuration was created.

Example:"2025-04-03 13:40:54.056794-06:00"
updatedAtstring, (date-time)

Timestamp when the webhook configuration was last updated.

Example:"2025-04-03 13:40:54.056794-06:00"
deletedAtnull or string

Timestamp when the webhook configuration was deleted, or null.

Example:null
blockedAtnull or string

Timestamp when the webhook configuration was blocked, or null.

Example:null
deletedBynull or string

Identifier of the actor that deleted the webhook, or null.

Example:null
blockedBynull or string

Identifier of the actor that blocked the webhook, or null.

Example:null

Response example

Response
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhookType": "MONEY_IN",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-04-03 13:40:54.056794-06:00",
  "updatedAt": "2025-04-03 13:40:54.056794-06:00",
  "deletedAt": null,
  "blockedAt": null,
  "deletedBy": null,
  "blockedBy": null
}
ErrorWhen it happens
400Required webhook fields are missing or malformed, or a matching webhook configuration already exists.
401The bearer token is missing, expired, invalid, or not valid for the environment.
500Unexpected server error.

List webhook configurations

Endpoint: GET /v1/clients/{clientId}/webhooks

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Path parameters

clientIdstring, (uuid)required

Client UUID that owns the webhooks.

Request body

No request body.

Request example

Payload
// No request payload

200 response body

currentPageintegerrequired

Current page number.

Example:0
perPageintegerrequired

Number of webhook configurations returned per page.

Example:50
totalItemintegerrequired

Total number of webhook configurations matching the request.

Example:2
dataArray of objectsrequired

Webhook configurations returned for the client.

Response example

Response
{
  "currentPage": 0,
  "perPage": 50,
  "totalItem": 2,
  "data": [null]
}
ErrorWhen it happens
400Request parameters are malformed.
401The bearer token is missing, expired, invalid, or not valid for the environment.
500Unexpected server error.

Retrieve webhook configuration

Endpoint: GET /v1/clients/{clientId}/webhooks/{webhookId}

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Path parameters

clientIdstring, (uuid)required

Client UUID that owns the webhook.

idstring, (uuid)required

Webhook UUID.

Request body

No request body.

Request example

Payload
// No request payload

200 response body

idstring, (uuid)required

Webhook configuration UUID.

Example:"29806117-2b15-4682-87f0-350e6695fe91"
clientIdstring, (uuid)required

Client UUID that owns the webhook.

Example:"c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring, (uri)required

Destination URL where Monato sends webhook events.

Example:"https://example.com/webhook"
webhookTypestringrequired

Type of events delivered to this webhook.

Enum:"MONEY_IN""STATUS_UPDATE""CEP""REPORT""REFUND"
Example:"MONEY_IN"
webhookStatusstringrequired

Current webhook lifecycle status.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
tokenstring

Secret configured for webhook delivery.

Example:"secretToken0123"
createdAtstring, (date-time)

Timestamp when the webhook configuration was created.

Example:"2025-04-03 13:40:54.056794-06:00"
updatedAtstring, (date-time)

Timestamp when the webhook configuration was last updated.

Example:"2025-04-03 13:40:54.056794-06:00"
deletedAtnull or string

Timestamp when the webhook configuration was deleted, or null.

Example:null
blockedAtnull or string

Timestamp when the webhook configuration was blocked, or null.

Example:null
deletedBynull or string

Identifier of the actor that deleted the webhook, or null.

Example:null
blockedBynull or string

Identifier of the actor that blocked the webhook, or null.

Example:null

Response example

Response
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhookType": "MONEY_IN",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-04-03 13:40:54.056794-06:00",
  "updatedAt": "2025-04-03 13:40:54.056794-06:00",
  "deletedAt": null,
  "blockedAt": null,
  "deletedBy": null,
  "blockedBy": null
}
ErrorWhen it happens
401The bearer token is missing, expired, invalid, or not valid for the environment.
404The webhook configuration was not found for the supplied client.

Update webhook configuration

Endpoint: PATCH /v1/clients/{clientId}/webhooks/{webhookId}

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Path parameters

clientIdstring, (uuid)required

Client UUID that owns the webhook.

idstring, (uuid)required

Webhook UUID.

Request body

urlstring, (uri)

New delivery URL for the webhook.

Example:"https://example.com/new-webhook"
tokenstring

New secret used to authenticate webhook delivery.

Example:"newTokenValue"
webhook_statusstring

New webhook lifecycle status.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
auth_client_idstring

OAuth client identifier used when auth_type is OAUTH.

Example:"oauth-client-id"
auth_client_secretstring

OAuth client secret used when auth_type is OAUTH.

Example:"oauth-client-secret"
auth_urlstring, (uri)

OAuth token endpoint used for webhook delivery authentication.

Example:"https://auth.example.com/oauth2/token"
auth_scopestring

OAuth scopes requested for webhook delivery authentication.

Example:"scope1 scope2"
auth_audiencestring

OAuth audience requested for webhook delivery authentication.

Example:"https://api.example.com"

Request example

Payload
{
  "url": "https://example.com/new-webhook",
  "webhook_status": "ACTIVE"
}

200 response body

idstring, (uuid)required

Webhook configuration UUID.

Example:"29806117-2b15-4682-87f0-350e6695fe91"
clientIdstring, (uuid)required

Client UUID that owns the webhook.

Example:"c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring, (uri)required

Destination URL where Monato sends webhook events.

Example:"https://example.com/webhook"
webhookTypestringrequired

Type of events delivered to this webhook.

Enum:"MONEY_IN""STATUS_UPDATE""CEP""REPORT""REFUND"
Example:"MONEY_IN"
webhookStatusstringrequired

Current webhook lifecycle status.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
tokenstring

Secret configured for webhook delivery.

Example:"secretToken0123"
createdAtstring, (date-time)

Timestamp when the webhook configuration was created.

Example:"2025-04-03 13:40:54.056794-06:00"
updatedAtstring, (date-time)

Timestamp when the webhook configuration was last updated.

Example:"2025-04-03 13:40:54.056794-06:00"
deletedAtnull or string

Timestamp when the webhook configuration was deleted, or null.

Example:null
blockedAtnull or string

Timestamp when the webhook configuration was blocked, or null.

Example:null
deletedBynull or string

Identifier of the actor that deleted the webhook, or null.

Example:null
blockedBynull or string

Identifier of the actor that blocked the webhook, or null.

Example:null

Response example

Response
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhookType": "MONEY_IN",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-04-03 13:40:54.056794-06:00",
  "updatedAt": "2025-04-03 13:40:54.056794-06:00",
  "deletedAt": null,
  "blockedAt": null,
  "deletedBy": null,
  "blockedBy": null
}
ErrorWhen it happens
400Webhook update fields are missing or malformed.
401The bearer token is missing, expired, invalid, or not valid for the environment.
404The webhook configuration was not found for the supplied client.

Delete webhook configuration

Endpoint: DELETE /v1/clients/{clientId}/webhooks/{webhookId}

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Path parameters

clientIdstring, (uuid)required

Client UUID that owns the webhook.

idstring, (uuid)required

Webhook UUID.

Request body

No request body.

Request example

Payload
// No request payload

200 response body

idstring, (uuid)required

Webhook configuration UUID.

Example:"29806117-2b15-4682-87f0-350e6695fe91"
clientIdstring, (uuid)required

Client UUID that owns the webhook.

Example:"c2d1d1e3-3340-4170-980e-e9269bbbc551"
urlstring, (uri)required

Destination URL where Monato sends webhook events.

Example:"https://example.com/webhook"
webhookTypestringrequired

Type of events delivered to this webhook.

Enum:"MONEY_IN""STATUS_UPDATE""CEP""REPORT""REFUND"
Example:"MONEY_IN"
webhookStatusstringrequired

Current webhook lifecycle status.

Enum:"ACTIVE""INACTIVE"
Example:"ACTIVE"
tokenstring

Secret configured for webhook delivery.

Example:"secretToken0123"
createdAtstring, (date-time)

Timestamp when the webhook configuration was created.

Example:"2025-04-03 13:40:54.056794-06:00"
updatedAtstring, (date-time)

Timestamp when the webhook configuration was last updated.

Example:"2025-04-03 13:40:54.056794-06:00"
deletedAtnull or string

Timestamp when the webhook configuration was deleted, or null.

Example:null
blockedAtnull or string

Timestamp when the webhook configuration was blocked, or null.

Example:null
deletedBynull or string

Identifier of the actor that deleted the webhook, or null.

Example:null
blockedBynull or string

Identifier of the actor that blocked the webhook, or null.

Example:null

Response example

Response
{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhookType": "MONEY_IN",
  "webhookStatus": "ACTIVE",
  "createdAt": "2025-04-03 13:40:54.056794-06:00",
  "updatedAt": "2025-04-03 13:40:54.056794-06:00",
  "deletedAt": null,
  "blockedAt": null,
  "deletedBy": null,
  "blockedBy": null
}
ErrorWhen it happens
401The bearer token is missing, expired, invalid, or not valid for the environment.
404The webhook configuration was not found for the supplied client.

Status update webhook event

Webhook event: POST status-update

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request body

id_msgstring, (uuid)required

Unique message identifier for deduplication.

Example:"35066b9c-e1e3-4d1b-89e6-35c036a70b00"
msg_namestringrequired

Event name. For status notifications it is always STATUS_UPDATE.

Value:"STATUS_UPDATE"
Example:"STATUS_UPDATE"
msg_datestring, (date)required

Event date in YYYY-MM-DD format.

Example:"2025-08-27"
bodyobjectrequired

Transaction status update payload.

Request example

{
  "id_msg": "35066b9c-e1e3-4d1b-89e6-35c036a70b00",
  "msg_name": "STATUS_UPDATE",
  "msg_date": "2025-08-27",
  "body": {
    "id": "6fd78718-106c-485d-824d-f6c3e8133571",
    "tracking_key": "20250827FINCH5CJS56XDFE",
    "message_type": "SPEI",
    "reason": "CANCELLED_ACCOUNT",
    "reason_description": "Cuenta cancelada",
    "status": "INITIALIZED",
    "update_at": "2025-08-27T15:40:44.413078-06:00"
  }
}

200 response body

No response body.

Response example

No response body for successful acknowledgements.

ErrorWhen it happens
422Your system received the event but could not process it as valid.

CEP webhook event

Webhook event: POST cep

This event is emitted on every CEP status change except INITIALIZED, so a single validation can produce several events before reaching COMPLETED or FAILED. See CEP Statuses for the full lifecycle and the transitions between statuses.

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request body

id_msgstring, (uuid)required

Unique message identifier (use for idempotency/deduplication)

Example:"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
msg_namestringrequired

Event name

Value:"CEP"
Example:"CEP"
msg_datestring, (date)required

Event date (YYYY-MM-DD)

Example:"2025-08-15"
bodyobjectrequired

CEP update payload.

Request example

{
  "id_msg": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "msg_name": "CEP",
  "msg_date": "2025-08-15",
  "body": {
    "id": "11111111-2222-3333-4444-555555555555",
    "tracking_key": "20250815XXXXXX123456789",
    "beneficiary_account": "000000000000000000",
    "beneficiary_name": "Daniela Paola Santelices Chavez",
    "beneficiary_rfc": "XXXX000000XXX",
    "status": "DELAYED",
    "processed_at": "2025-08-15T22:42:39.327Z"
  }
}

200 response body

No response body.

Response example

No response body for successful acknowledgements.

ErrorWhen it happens
422Your system received the event but could not process it as valid.

Refund webhook event

Webhook event: POST refund

Monato sends this event when a refund transaction is created. There are two cases, and the second one is not triggered by you:

  • You call the refund endpoint for a Money In.
  • An outbound SPEI transfer is reversed by the banking network.

Register this webhook if you need to reconcile reversals you did not initiate.

The body describes the refund transaction, not the original one. Use original_transaction_id and original_transaction_tracking_id to link it back to the transaction being refunded. Partial refunds are not supported, so amount always equals original_transaction_amount.

Headers

Authorizationstringrequired

Bearer token returned by the authentication flow.

Example:"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Request body

id_msgstring, (uuid)required

Unique message identifier (use for idempotency/deduplication)

Example:"f0b1c6de-6a3c-4f2e-9d47-1c0a5b7e2d38"
msg_namestringrequired

Event name. For refund notifications it is always REFUND.

Value:"REFUND"
Example:"REFUND"
msg_datestring, (date)required

Event date (YYYY-MM-DD)

Example:"2026-09-21"
bodyobjectrequired

Refund transaction payload.

Request example

{
  "id_msg": "f0b1c6de-6a3c-4f2e-9d47-1c0a5b7e2d38",
  "msg_name": "REFUND",
  "msg_date": "2026-09-21",
  "body": {
    "id": "0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "tracking_key": "20260921FINCHXXXXQ6RPX4",
    "beneficiary_account": "734180000000001004",
    "beneficiary_name": "Carolina Perez Marquez",
    "beneficiary_rfc": "XAXX010101000",
    "payer_account": "734185000000000055",
    "payer_name": "FINCO PAY",
    "payer_rfc": "XAXX010101000",
    "payer_institution": "90734",
    "amount": "150.00",
    "transaction_date": "2026-09-21 13:03:36",
    "category": "CREDIT_TRANS",
    "sub_category": "SPEI_REFUNDED_CREDIT",
    "payment_concept": "Refund due to incorrect amount",
    "numeric_reference": "1234567",
    "original_transaction_id": "1eb4b5ac-71f6-4203-aded-4fcb7fd21637",
    "original_transaction_tracking_id": "20260920FINCHZ43V14QILB",
    "original_transaction_amount": "150.00"
  }
}

200 response body

No response body.

Response example

No response body for successful acknowledgements.

ErrorWhen it happens
422Your system received the event but could not process it as valid.

Transactions

Money In

© 2025 by Monato. All rights reserved.