Webhook events

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

Configure only the types your product flow needs. Register REFUND if you need to reconcile reversals you did not initiate.

Manage webhook configurations

All operations are scoped to your client and use Authorization: Bearer <token>.

curl -X POST https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
    "url": "https://example.com/webhook",
    "token": "'"$WEBHOOK_TOKEN"'",
    "webhook_type": "MONEY_IN",
    "auth_type": "AUTH"
  }'

{
  "id": "29806117-2b15-4682-87f0-350e6695fe91",
  "clientId": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "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
}

Registering fails with 400 if a field is missing or malformed, the URL does not meet delivery requirements, or a matching configuration already exists.

To update a webhook, send only the fields you want to change. At least one is required: url, token, webhook_status (ACTIVE or INACTIVE), and for OAuth delivery auth_client_id, auth_client_secret, auth_url, auth_scope and auth_audience.

curl -X PATCH https://apicore.stg.finch.lat/v1/clients/$CLIENT_ID/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/new-webhook",
    "webhook_status": "ACTIVE"
  }'

Respond to events

Your endpoint must return its HTTP response within 5 seconds of receiving a webhook request. This applies to every event type.

Finish the validations you need to accept or reject the event within that window. Persist the event safely before you acknowledge it, then do any remaining processing asynchronously. For external Money In, decide to accept or reject before you respond; see Receive money.

The 422 status only appears in this direction, as a response your endpoint returns. Fincore itself does not return 422 on any request.

Security and deduplication

• Store webhook tokens securely. Do not expose them in logs or frontend code.
• Validate the event type (msg_name) and the message identifier (id_msg) before processing.
• Deduplicate by id_msg. If an event was already processed correctly, return a success status again.
• Never rely only on delivery order. Store the transaction ID and tracking key for reconciliation.

Event envelope

Money In, status update, CEP and refund events share the same envelope:

The report event is flat and does not use this envelope.

Every webhook request from Monato includes a required Authorization: Bearer <token> header.

Money In

Sent when funds arrive into one of your accounts, from an external SPEI credit or an internal (book-to-book) credit. Operation: webhookMoneyInPost. See Receive money for how to handle it.

{
  "id_msg": "a7a126e8-fa74-411c-ad2b-b000f277bb0d",
  "msg_name": "MONEY_IN",
  "msg_date": "2025-04-02",
  "body": {
    "id": "0196da9a-8947-703e-9a3b-bf8c7d9f6059",
    "beneficiary_account": "734180000000000001",
    "beneficiary_name": "John Smith",
    "beneficiary_rfc": "XAXX010101000",
    "payer_account": "123456789012345678",
    "payer_name": "Jane Doe",
    "payer_rfc": "XAXX010101000",
    "payer_institution": "40002",
    "amount": "1500.00",
    "transaction_date": "2025-04-02 10:14:05",
    "tracking_key": "50118609TBRNZ00I07219647",
    "payment_concept": "Payment for invoice 4567",
    "numeric_reference": "2504021",
    "sub_category": "SPEI_CREDIT",
    "registered_at": "2025-04-02T10:14:05.915184-06:00",
    "owner_id": "24f1e5d5-4045-4b1a-a0c4-5e6c6b1d44ef"
  }
}

INT_CREDIT events are emitted only when the credit is for a different owner than the initiator. Self-transfers under the same client_id and owner_id do not generate a MONEY_IN event.

Status update

Sent when a Money Out transaction status changes. Operation: webhookStatusUpdatePost. Status values are listed in Transaction statuses.

{
  "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",
    "status": "LIQUIDATED",
    "update_at": "2025-08-27T15:40:44.413078-06:00"
  }
}

Respond 200 (received) or 202 (received, processing asynchronously). Return 422 if your system received the event but could not process it as valid.

CEP

Sent for Penny Validation transactions only (amount = 0.01 MXN), on every CEP status change except INITIALIZED, which may appear on API reads only and should be treated as PENDING. A single validation can produce several events before it reaches COMPLETED or FAILED. Operation: webhookCepPost. See CEP statuses.

{
  "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": "Jane Doe",
    "beneficiary_rfc": "XAXX010101000",
    "status": "DELAYED",
    "processed_at": "2025-08-15T22:42:39.327Z"
  }
}

Respond 200 (accepted) or 202 (accepted, validating asynchronously). Return 422 if your system could not process the event as valid.

Refund

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

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

Operation: webhookRefundPost.

{
  "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": "734180000000000001",
    "beneficiary_name": "Jane Doe",
    "beneficiary_rfc": "XAXX010101000",
    "payer_account": "734180000000000055",
    "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"
  }
}

The body describes the refund transaction, not the original one. id and tracking_key belong to the refund. 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.

Respond 200 (accepted) or 202 (processing asynchronously). Return 422 if your system could not process the event as valid.

Report

Sent when a generated file is available for download: transaction reports or account statements, daily or monthly. Operation: webhookReportPost. This event is not wrapped in the envelope.

{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "file_type": "ACCOUNT_STATEMENT",
  "period": "MONTHLY",
  "file_name": "account_statement_1234567890_202602.csv",
  "created_at": "2026-03-01T02:10:00Z",
  "account_id": "1234567890"
}

Respond 200 (received) or 202 (processing asynchronously).