Saltar al contenido principal
Los webhooks permiten a AgencyHandy enviar datos a sus sistemas externos en el momento en que algo cambia, sin necesidad de sondeo (polling). Cuando se dispara un evento configurado (por ejemplo, se actualiza un pedido o se crea un ticket), AgencyHandy envía una solicitud HTTP POST con una carga útil JSON a la URL del endpoint que usted especifique. Esto facilita mantener herramientas externas como CRM, sistemas de facturación o paneles personalizados sincronizados con su espacio de trabajo de AgencyHandy en tiempo real.
Los espacios de trabajo del plan Business Pro admiten hasta 30,000 eventos de webhook por período de facturación. Verifique los límites de su plan antes de configurar automatizaciones de alto volumen.

​
Eventos admitidos

Puede suscribir un webhook a cualquier combinación de los siguientes eventos:
CategoríaEventos
ServiceCreated, Updated, Deleted
OrderCreated, Updated, Deleted
TaskCreated, Assigned, Completed, Updated
InvoiceStatus changed
Client / UserNew client added, Client/user deleted
ProposalSent, Received, Accepted, Rejected
TicketCreated, Assigned, Status changed
PaymentReceived, Failed
Service PackageCreated, Updated, Deleted

​
Crear un webhook

1

Ir a Webhook Management

En la barra lateral izquierda, vaya a Integrations → Webhooks Management.
2

Autenticar su token

Haga clic en el botón Management para autenticar su token de webhook. Este token se utiliza para firmar las cargas útiles salientes, de modo que pueda verificar que se originaron en AgencyHandy.
3

Crear un nuevo webhook

Haga clic en Create New Webhook para abrir el formulario de configuración del webhook.
4

Introducir la URL del endpoint

En el campo Endpoint URL, introduzca la URL del sistema externo que debe recibir los datos del webhook. Debe ser un endpoint POST de acceso público.
5

Seleccionar el tipo de contenido

Elija JSON como tipo de contenido. AgencyHandy envía todas las cargas útiles de webhook como application/json.
6

Seleccionar los eventos del webhook

Elija cada evento que debe activar este webhook. Puede seleccionar eventos de varias categorías — por ejemplo, Order: Created e Invoice: Status changed pueden apuntar ambos al mismo endpoint.
7

Activar el webhook

Active el botón de opción Active. Cuando está activo, AgencyHandy entrega las cargas útiles de todos los eventos seleccionados a su endpoint en tiempo real.
8

Guardar la configuración

Revise su configuración y luego haga clic en Save. El webhook aparece en la lista y comienza a entregar eventos de inmediato.

​
Probar un webhook

Después de crear un webhook, envíe una carga útil de prueba para confirmar que su endpoint es accesible y procesa los datos correctamente.
1

Abrir el webhook

En la lista de Webhooks Management, haga clic en el webhook que desea probar.
2

Hacer clic en Test Event

Haga clic en el botón Test Event en la página de detalles del webhook.
3

Seleccionar un evento de prueba

Elija un evento de ejemplo de la lista de eventos configurados en este webhook (p. ej., Order: Created).
4

Enviar la carga útil de prueba

Haga clic en Send. AgencyHandy publica una carga útil de ejemplo en la URL de su endpoint.
5

Verificar el resultado

Compruebe su sistema externo para confirmar que la carga útil de prueba llegó y se procesó como se esperaba. De vuelta en AgencyHandy, haga clic en el webhook para revisar su historial — puede ver la solicitud completa, la respuesta que devolvió su endpoint y reenviar cualquier evento anterior si es necesario.
Use una herramienta como Webhook.site o RequestBin como endpoint temporal durante la configuración para inspeccionar la forma exacta de la carga útil antes de conectar su sistema real.

​
Autenticar las cargas útiles de los webhooks

Cada solicitud de webhook saliente de AgencyHandy incluye un encabezado de firma que su endpoint puede usar para verificar que la carga útil es genuina y no ha sido manipulada.

​
Encabezado de firma

x-ah-sig: <signature>
AgencyHandy añade este encabezado a cada solicitud de webhook. Extraiga el valor de las solicitudes entrantes y páselo al endpoint de verificación.

​
Verificar la firma de un webhook

Envíe la siguiente solicitud para confirmar que una carga útil es auténtica: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
requerido
El ID del webhook que recibió el evento. Lo encontrará en la página de detalles del webhook en AgencyHandy.
​
signature
string
requerido
El valor del encabezado x-ah-sig de la solicitud de webhook entrante.
​
secret
string
requerido
El secreto del webhook que se muestra en la página de detalles del webhook en AgencyHandy.
​
payload
object
requerido
El cuerpo JSON sin procesar recibido de la solicitud de webhook de AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Respuestas
​
verification_status
string
SUCCESS cuando la firma es válida. FAILED cuando la verificación falla (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Mantenga su secreto de webhook confidencial. Rótelo periódicamente y actualice su lógica de verificación inmediatamente después de la rotación. Nunca lo exponga en código del lado del cliente ni en repositorios públicos.

​
Notas importantes

  • La URL de su endpoint debe ser una URL POST HTTPS de acceso público.
  • Si su endpoint está temporalmente no disponible, consulte el panel de historial del webhook en AgencyHandy — puede reenviar cualquier evento anterior directamente desde allí.
  • Supervise regularmente la actividad de los webhooks para detectar entregas fallidas o intentos de acceso no autorizado.
  • Los webhooks que fallan repetidamente pueden ser pausados por AgencyHandy — revise los registros de entrega para detectar problemas a tiempo.