Configurar webhooks para que los estados se actualicen solos

Un webhook es un mensaje que un sistema envía a otro cuando ocurre algo. Payload envía uno a Salesforce cuando un pago se procesa, se rechaza, se reembolsa, se anula o es devuelto por el banco, y cuando se deposita o se retira dinero de tu cuenta bancaria. REDA Pay recibe estos mensajes y actualiza la Pay Transaction correspondiente, o crea una Statement Activity para un depósito. Sin webhooks, un pago aceptado hoy y devuelto por el banco tres días después sigue como "processed" en Salesforce hasta que alguien pulse Sync Transaction a mano.

La configuración tiene cinco partes: una dirección pública en Salesforce a la que Payload pueda llegar, acceso para el usuario invitado detrás de esa dirección, la dirección en el Pay Profile, acceso para el usuario de Salesforce que procesa los mensajes y el botón Setup Webhooks, que registra la dirección en Payload.

Cómo encajan las piezas

Payload ──(mensaje webhook)──▶ tu sitio público de Salesforce ──▶ REDA Pay ──▶ Pay Transaction actualizada
                                 /services/apexrest/…              (procesado por el usuario Automated Process)

Payload necesita una dirección a la que pueda llamar sin iniciar sesión. En Salesforce, eso es un sitio: una dirección web pública de tu organización, que aquí se usa solo como buzón para los mensajes de Payload. REDA Pay le indica a Payload la dirección completa; tú solo aportas la dirección base del sitio.

Parte 1: crear el sitio público

Si tu organización ya tiene un sitio de Salesforce para integraciones, puedes reutilizarlo y pasar a la Parte 2. Si no:

1. Abre Configuración, escribe Sitios en el cuadro Búsqueda rápida y haz clic en Sitios, debajo de Interfaz de usuario → Sitios y dominios.
2. Si nunca creaste un sitio, registra primero un dominio: ingresa un nombre, haz clic en Comprobar disponibilidad, acepta los términos y haz clic en Registrar mi dominio de Salesforce Site. El dominio tiene la forma yourcompany.my.salesforce-sites.com.
3. Haz clic en Nuevo.
4. Completa Etiqueta del sitio (por ejemplo, Payment Callbacks), Nombre del sitio Web (se completa solo), Dirección web predeterminada (una ruta corta como rpay, que pasa a formar parte de la dirección) y Página de inicio de sitio Web activa: haz clic en el selector y elige cualquier página, por ejemplo UnderConstruction. Nadie visitará esta página.
5. Marca Activo y haz clic en Guardar.

Anota la dirección completa del sitio que aparece en URL del sitio, por ejemplo https://yourcompany.my.salesforce-sites.com/rpay.

La página de detalles del sitio para los callbacks de pago (llamado REDA Payload en esta organización de ejemplo): Etiqueta y Nombre del sitio, Activo marcado, los inicios de sesión no permitidos, las páginas de inicio y el botón Configuración de acceso público

Un sitio usado solo para webhooks. Su URL del sitio es lo que va en el Pay Profile.

Parte 2: dar acceso al usuario invitado del sitio

Cada sitio tiene un usuario invitado, la identidad que Salesforce usa para los visitantes que no iniciaron sesión. Los mensajes de Payload llegan como ese usuario, así que debe poder ejecutar la clase de REDA Pay que los recibe.

1. En la página de detalles del sitio, haz clic en Configuración de acceso público. Se abre el perfil del usuario invitado.
2. Busca Acceso a clases de Apex activado (en la interfaz de perfil mejorada se llama Acceso a clase de Apex) y haz clic en Modificar.
3. Mueve rpay.PayloadCallback de la lista de disponibles a la de habilitadas y haz clic en Guardar. El usuario invitado no necesita nada más: esta clase solo entrega el mensaje a REDA Pay.

La sección Acceso a clase de Apex del perfil del usuario invitado del sitio (interfaz de perfil mejorada) con rpay.PayloadCallback

El usuario invitado necesita exactamente esta clase. Recibe el mensaje de Payload y se lo entrega a REDA Pay.

Parte 3: poner la dirección del sitio en el Pay Profile

1. Abre la app REDA Pay → Pay Profiles → tu perfil → Modificar.
2. En Webhook API Base URL, pega la dirección del sitio de la Parte 1, con https:// y la ruta, por ejemplo https://yourcompany.my.salesforce-sites.com/rpay.
3. Haz clic en Guardar.

REDA Pay agrega el resto de la dirección por su cuenta. Nunca escribes la dirección completa del webhook.

Parte 4: dar acceso al usuario Automated Process

Cuando llega un mensaje, Salesforce se lo entrega a un usuario de sistema integrado llamado Automated Process (Salesforce en español lo muestra como Proceso automatizado). Ese usuario hace el trabajo: lee el mensaje, busca la Pay Transaction, le pide a Payload su estado más reciente y actualiza el registro. No tiene acceso a los registros de REDA Pay hasta que se lo das, y no aparece en la lista normal de usuarios, así que el acceso se concede con un script corto.

1. Abre Configuración → Conjuntos de permisos, abre REDA Pay - Admin User y haz clic en Duplicar. Llama a la copia REDA Pay - Automated Process y haz clic en Guardar.
2. Copia el Id de la copia desde la barra de direcciones (los 18 caracteres después de /lightning/setup/PermSets/, o los 15 caracteres después de id=).
3. Abre la Developer Console (consola para desarrolladores) desde el menú del engranaje y luego Debug → Open Execute Anonymous Window (la ventana para ejecutar código anónimo); la Developer Console muestra sus menús en inglés. Pega la línea siguiente con tu Id y haz clic en Execute:

insert new PermissionSetAssignment(
    AssigneeId = [SELECT Id FROM User WHERE Alias = 'autoproc' LIMIT 1].Id,
    PermissionSetId = '0PS000000000000AAA'   // el Id de tu conjunto de permisos REDA Pay - Automated Process
);

La ventana informa que se ejecutó correctamente. Si informa que la asignación ya existe, el paso ya se había hecho.

Parte 5: registrar los webhooks en Payload

1. En el Pay Profile, haz clic en Setup Webhooks.
2. Lee el diálogo: "System will delete all the existng webhooks and create new webhook setup." (el sistema eliminará todos los webhooks existentes y creará una configuración nueva).
3. Haz clic en Setup Webhooks. Espera el mensaje "Webhook setup created successfully." y cierra el diálogo.
4. Abre la pestaña Webhook Setup del perfil. Muestra diez registros Pay Profile Webhook, uno por evento: payment, processed, authorized, credit, refund, reversal, void, decline, deposit y reject. Cada uno muestra el Webhook Id que asignó Payload y la Webhook URL que registró REDA Pay. El campo Webhook Setup Datetime [Payload] del perfil queda completado.

La pestaña Webhook Setup de un Pay Profile con diez Pay Profile Webhooks (payment, processed, authorized, credit, refund, reversal, void, decline, deposit, reject) y sus columnas Webhook Id y Webhook URL

Diez webhooks, uno por evento de Payload. Si aparecen menos, el registro falló a medias: corrige la causa y vuelve a ejecutar Setup Webhooks.

Vuelve a ejecutar Setup Webhooks cada vez que cambies la Webhook API Base URL o reemplaces la clave de API.

Comprobar que funciona

Cobra un pago de prueba pequeño (consulta Cobrar un pago) y abre su Pay Transaction. En pocos minutos, los campos Status, Status Code y Funding Status se actualizan sin que nadie pulse Sync Transaction. En un pago bancario, el estado de fondeo pasa de pending a batched cuando Payload lo incluye en un lote, y más tarde un depósito en tu cuenta bancaria crea una Statement Activity; consulta Conciliar depósitos y pagos salientes.

Si nada se actualiza, revisa en este orden:

Qué contienen los mensajes

Un mensaje solo le dice a REDA Pay qué transacción cambió. REDA Pay le pide entonces a Payload el estado actual de esa transacción y guarda la respuesta, así que el registro siempre refleja a Payload y no al mensaje. Se ignoran los mensajes sobre transacciones que Salesforce nunca vio. Los mensajes de depósito y de retiro crean o actualizan una Statement Activity.

Errores que debes evitar

Preguntas frecuentes

Qué sigue

• Cómo se mantienen al día los estados de los pagos: qué hace cada evento con los registros.
• Activar la recuperación de pagos fallidos: el trabajo que cubre los pagos cuyo resultado nunca llegó.