Register a webhook for a client

POST /v1/clients/{clientId}/webhooks

Base URL https://apicore.stg.finch.lat · operationId createClientWebhook

Endpoint to register a new URL where the specified client will receive webhooks. Requires Authorization: Bearer <token> headers.

Authorization

bearerAuth Bearer token

JWT bearer token created from client credentials. Use the Authentication guide to generate a token before calling protected endpoints.

Path parameters

clientId string (uuid) required

Client UUID for which the webhook is being registered.

Request body application/json · required

client_id string (uuid) required

Client UUID that owns the webhook configuration.

url string (uri) required

Public HTTPS URL where Monato sends webhook events.

token string required

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

webhook_type string required

Type of event delivered to this webhook.

MONEY_IN STATUS_UPDATE CEP REPORT REFUND

auth_type string required

Authentication mode used when Monato delivers webhook events.

AUTH NO_AUTH OAUTH

Responses

200 Webhook successfully created application/json

id string (uuid) required

Webhook configuration UUID.

clientId string (uuid) required

Client UUID that owns the webhook.

url string (uri) required

Destination URL where Monato sends webhook events.

token string

Secret configured for webhook delivery.

webhookType string required

Type of events delivered to this webhook.

MONEY_IN STATUS_UPDATE CEP REPORT REFUND

webhookStatus string required

Current webhook lifecycle status.

ACTIVE INACTIVE

createdAt string (date-time)

Timestamp when the webhook configuration was created.

updatedAt string (date-time)

Timestamp when the webhook configuration was last updated.

deletedAt string | null

Timestamp when the webhook configuration was deleted, or null.

blockedAt string | null

Timestamp when the webhook configuration was blocked, or null.

deletedBy string | null

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

blockedBy string | null

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

400 Webhook creation request is invalid. Possible causes: malformed client_id, invalid URL, missing token, unsupported webhook_type, unsupported auth_type, or URL that does not meet delivery requirements. It also fails when a matching webhook configuration already exists. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Missing, expired, invalid, or environment-mismatched API key or bearer token. See Authentication. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

This request is in the Monato · Fincore Postman collection, folder Webhooks.Download collection

Request

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

const body = JSON.stringify({
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "url": "https://example.com/webhook",
  "token": "secretToken0123",
  "webhook_type": "MONEY_IN",
  "auth_type": "AUTH"
});

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

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

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/webhooks",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

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
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 16,
  "message": "API Error",
  "details": [
    {
      "reason": "UNAUTHORIZED",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid Credentials",
        "http_code": "401"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}