Create Webhook

POST /api/v1/cash/webhooks

Base URL https://dev-api.finco.lat · operationId createWebhook

Allows authenticated clients to configure webhook endpoints for receiving real-time notifications about operation status changes. The webhook is only activated if the activation test is successful.

Webhook Events: After configuration, your endpoint will receive:

Activation test: See WebhookActivationEvent schema below
Status updates: See OperationStatusUpdateEvent schema below

Note: Only one active webhook is allowed per client. Creating a new webhook will deactivate any existing ones after successful activation.

Authorization

ClientAuth API key in header X-Client-Id

Client API key (32-character hex) obtained from client creation process. Must be used with X-Signature and X-Timestamp headers for HMAC authentication.

HMACSignature API key in header X-Signature

HMAC-SHA256 signature generated using your api_secret. Format: HMAC-SHA256(timestamp + "." + requestBody, api_secret)

Timestamp API key in header X-Timestamp

Unix timestamp (seconds since epoch) when the request was created. Used in HMAC signature generation to prevent replay attacks.

Request body application/json · required

endpoint_url string (uri) required

The webhook endpoint URL where notifications will be sent (must use http or https protocol)

Responses

201 Webhook configured successfully. An activation test will be sent to your endpoint. application/json

The webhook will be marked as active only if your endpoint responds successfully to the test.

event string

Event type identifier

webhook.created

id integer

Unique identifier for the webhook configuration

endpoint_url string (uri)

The configured webhook endpoint URL

secret_token string

64-character hexadecimal secret token for webhook signature verification

created_at string (date-time)

ISO 8601 timestamp of webhook configuration creation

400 Bad Request - Invalid webhook configuration application/json

event string

Event type identifier

webhook.failed

errors object | string | array of string

401 Unauthorized - Invalid or missing authentication application/json

error string

Error message

Callback: Customer Webhook Endpoint

POST {$request.body#/endpoint_url}

Webhook notifications sent by Monato

After webhook activation, Monato will send POST requests to your configured endpoint with operation status updates. All requests include signature headers for verification.

Headers

X-Webhook-Timestamp string required

Unix timestamp when the webhook was sent

Example 1705312200

X-Webhook-Signature string required

HMAC-SHA256 signature for webhook verification

Example a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

Payload application/json

One of WebhookActivationEvent

Webhook activation test event sent to your endpoint during configuration

event event string

Event type identifier

webhook.activation

processed_at processed_at string (date-time)

ISO 8601 timestamp when the activation test was processed

One of OperationStatusUpdateEvent

Operation status update event sent to your webhook endpoint

event event string

Event type identifier

webhook.paid.success webhook.expired.success webhook.reversed.success

operation_id operation_id integer

Unique identifier for the operation

external_user_id external_user_id string

Unique identifier for the end user

type type string

Operation type

cash_in cash_out

amount amount integer

Transaction amount in MXN

reference reference string

20-digit operation reference number

status status string

New operation status

paid expired reversed

processed_at processed_at string (date-time)

ISO 8601 timestamp when the status was updated

{
  "event": "webhook.activation",
  "processed_at": "2025-01-15T10:30:00Z"
}

{
  "event": "webhook.paid.success",
  "operation_id": 123,
  "external_user_id": "USER123456",
  "type": "cash_in",
  "amount": 500,
  "reference": "10511175512161627448",
  "status": "paid",
  "processed_at": "2025-01-15T10:30:00Z"
}

{
  "event": "webhook.expired.success",
  "operation_id": 123,
  "external_user_id": "USER123456",
  "type": "cash_in",
  "amount": 500,
  "reference": "10511175512161627448",
  "status": "expired",
  "processed_at": "2025-01-15T10:30:00Z"
}

{
  "event": "webhook.reversed.success",
  "operation_id": 123,
  "external_user_id": "USER123456",
  "type": "cash_in",
  "amount": 500,
  "reference": "10511175512161627448",
  "status": "reversed",
  "processed_at": "2025-01-15T10:30:00Z"
}

Expected responses

200 Webhook received and processed successfully by client

400 Client rejected the webhook (invalid data)

500 Client server error processing webhook

This request is in the Monato · Cash Postman collection.Download collection

Request

# SIGNATURE = HMAC-SHA256(TIMESTAMP + "." + request body, api_secret)
curl -X POST "https://dev-api.finco.lat/api/v1/cash/webhooks" \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Content-Type: application/json" \
  -d '{
  "endpoint_url": "https://your-webhook-endpoint.com/webhooks"
}'

import crypto from "node:crypto";

const body = JSON.stringify({
  "endpoint_url": "https://your-webhook-endpoint.com/webhooks"
});
const TIMESTAMP = Math.floor(Date.now() / 1000).toString();
const SIGNATURE = crypto.createHmac("sha256", API_SECRET).update(TIMESTAMP + "." + body).digest("hex");

const res = await fetch("https://dev-api.finco.lat/api/v1/cash/webhooks", {
  method: "POST",
  headers: {
    "X-Client-Id": CLIENT_ID,
    "X-Signature": SIGNATURE,
    "X-Timestamp": TIMESTAMP,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests
import hashlib
import hmac
import json
import time

payload = {
  "endpoint_url": "https://your-webhook-endpoint.com/webhooks"
}
body = json.dumps(payload, separators=(",", ":"))
TIMESTAMP = str(int(time.time()))
SIGNATURE = hmac.new(API_SECRET.encode(), f"{TIMESTAMP}.{body}".encode(), hashlib.sha256).hexdigest()

res = requests.post(
    "https://dev-api.finco.lat/api/v1/cash/webhooks",
    headers={
        "X-Client-Id": CLIENT_ID,
        "X-Signature": SIGNATURE,
        "X-Timestamp": TIMESTAMP,
        "Content-Type": "application/json",
    },
    data=body,
)
data = res.json()

Response

{
  "event": "webhook.created",
  "id": 456,
  "endpoint_url": "https://your-webhook-endpoint.com/webhooks",
  "secret_token": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c",
  "created_at": "2025-01-15T10:30:00Z"
}

{
  "event": "webhook.failed",
  "errors": {
    "endpoint_url": [
      "must be a valid URL"
    ]
  }
}

{
  "error": "Unauthorized"
}