Formato de Notificaciones Webhook

Una vez que tu suscripción está activa, FidiX enviará notificaciones automáticas a tu endpoint cada vez que ocurra un evento al que estés suscrito. Las notificaciones son entregadas por AWS SNS mediante un HTTP POST a la URL registrada.

Flujo de activación

La suscripción se crea.

Tu endpoint recibirá un mensaje de validación con SubscribeURL.

Debes invocar esa SubscribeURL para completar la validación.

Una vez confirmada, comenzará el envío de eventos a tu endpoint.

El campo delivery.confirmation_required en la respuesta de creación indica si este paso aplica para tu suscripción.

Tipos de mensajes

Tu endpoint puede recibir dos tipos de mensajes, identificados por el campo Type:

`Type`	Descripción
`SubscriptionConfirmation`	Mensaje de validación enviado al crear la suscripción. Requiere confirmar la `SubscribeURL`.
`Notification`	Notificación de un evento real (transferencia recibida, fallida, etc.).

Mensaje de confirmación

Cuando creás una suscripción y AWS SNS requiere confirmación, tu endpoint recibirá el siguiente mensaje. Debés hacer un HTTP GET a la SubscribeURL para activar el envío de eventos.

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "f73ad032-4577-4747-a857-2f1163e94a88",
  "Token": "2336412f37fb687f5d51e6e2425...",
  "TopicArn": "arn:aws:sns:us-east-1:653502182179:client_id_topic",
  "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:653502182179:client_id_topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:653502182179:client_id_topic&Token=2336412f37fb687f5d51e6e2425...",
  "Timestamp": "2026-05-19T14:07:52.258Z",
  "SignatureVersion": "1",
  "Signature": "VryLh9d1UXmbn2Ik...",
  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-7506a1e35b36ef5a444d..."
}

Notificaciones de eventos

Cuando ocurre un evento suscrito, tu endpoint recibirá un mensaje de tipo Notification.

⚠️ Importante: El campo Message llega como un string JSON escapado.

El campo MessageAttributes.event_type indica el tipo de evento y puede usarse para filtrar sin necesidad de parsear el Message.

Estructura general

{
  "Type": "Notification",
  "MessageId": "21ee62fd-33cf-5cc9-a36c-007bb322850f",
  "TopicArn": "arn:aws:sns:us-east-1:653502182179:client_id_topic",
  "Message": "{...}",
  "Timestamp": "2026-05-19T15:15:57.714Z",
  "SignatureVersion": "1",
  "Signature": "nvOtyFxGOKHgN3vk...",
  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-7506a1e35b36ef5a444...",
  "UnsubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=...",
  "MessageAttributes": {
    "event_type": {
      "Type": "String",
      "Value": "transfer.received"
    }
  }
}

Payload del evento (`Message` parseado)

El contenido del campo Message una vez parseado tiene la siguiente estructura:

{
  "id": "f8330421-b658-4d60-9d50-ff078bb275d1",
  "type": "transfer.received",
  "time": "2026-05-19T15:15:57.404922163Z",
  "data": {
    "ledger_data": {
      "id": "0f2483c3-4ce9-428c-b281-0a0bfd097586",
      "reference_id": "70196f79-d5c6-408c-a960-115a97777165",
      "ledger_id": "7b35fa34-bfef-4736-971c-90a2996bc892",
      "asset_id": "00000000-0000-0000-0000-000000000000",
      "type": "cash_in",
      "amount": "15",
      "currency": "CLP",
      "status": "POSTED",
      "metadata": {
        "bank_transfer_id": "70196f79-d5c6-408c-a960-115a97777165",
        "partner_id": "4fd99773-cee1-4d10-92dc-e25b7422906e"
      },
      "created_at": "2026-05-19T15:15:57.288867692Z",
      "updated_at": "2026-05-19T15:15:57.295981965Z",
      "posted_at": "2026-05-19T15:15:57.295981841Z"
    },
    "bank_data": {
      "accounting_date": "2026-02-26",
      "amount": "15.00",
      "bank_transfer_id": "70196f79-d5c6-408c-a960-115a97777165",
      "currency": "CLP",
      "description": "Transferencia Banco Chile",
      "destination": {
        "account_number": "0000000000123456789",
        "customer_identification": "19547456-9"
      },
      "executed_at": "2026-02-26T10:30:00Z",
      "metadata": {
        "id_cca": "000000000001"
      },
      "origin": {
        "account_number": "0000000123456789012",
        "customer_identification": "17547898-9",
        "customer_name": "Juan Gonzalez"
      },
      "status": "A",
      "virtual_account_alias": "8000000000000000001"
    }
  }
}

Descripción de campos del evento

Campo	Tipo	Descripción
`id`	UUID	Identificador único del evento.
`type`	string	Tipo de evento. Ej: `transfer.received`, `transfer.failed`, `transfer.pending`.
`time`	ISO 8601	Timestamp en que ocurrió el evento.
`data.ledger_data`	objeto	Información del movimiento registrado en el ledger de FidiX.
`data.ledger_data.id`	UUID	Id de la transacción en el ledger de FidiX.
`data.ledger_data.reference_id`	string	Id de referencia de la transacción en el ledger de FidiX.
`data.ledger_data.amount`	string	Monto de la transferencia.
`data.ledger_data.currency`	string	Moneda de la transferencia. Ej: `CLP`.
`data.ledger_data.status`	string	Estado del movimiento en el ledger. Ej: `POSTED`.
`data.bank_data`	objeto	Información de la transferencia bancaria original.
`data.bank_data.origin`	objeto	Datos del ordenante (nombre, RUT, cuenta de origen).
`data.bank_data.destination`	objeto	Datos de la cuenta de destino.
`data.bank_data.description`	string	Descripción o glosa de la transferencia.
`data.bank_data.virtual_account_alias`	string	Alias de la cuenta virtual de destino dentro de FidiX.

Webhooks

Formato de Notificaciones Webhook#

Flujo de activación#

Tipos de mensajes#

Mensaje de confirmación#

Notificaciones de eventos#

Estructura general#

Payload del evento (Message parseado)#

Descripción de campos del evento#