Desarrolladores
Webhooks firmados
Ally360 avisa a tu sistema cuando se paga una factura, cambian las existencias o la DIAN responde, con cada entrega firmada.
Cómo llegan
Crea el webhook en Configuración › Desarrolladores o con POST /v1/webhooks (permiso webhooks:manage). La URL debe ser https y pública. Cada entrega es un POST con este cuerpo y las cabeceras Ally360-Signature, Ally360-Event-Id, Ally360-Event-Type y Ally360-Delivery-Id. El objeto va en la misma forma que lo devuelve la API.
{
"id": "6b0c…",
"type": "invoice.paid",
"api_version": "2026-11-09",
"created_at": "2026-11-09T21:14:03-05:00",
"livemode": true,
"company_id": "3f1c…",
"data": {
"object": { "object": "invoice", "id": "…", "status": "paid", "total": "119000.00", "…": "…" },
"changes": { "type": "SALE", "status": "PAID" }
}
}Verifica la firma
Ally360-Signature: t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 del secreto sobre t, un punto y el cuerpo crudo. Rechaza una firma de más de 5 minutos y compara en tiempo constante. Usa el Ally360-Event-Id para no procesar dos veces el mismo evento.
import crypto from 'node:crypto'
import express from 'express'
const app = express()
const SECRETO = process.env.ALLY360_WEBHOOK_SECRET // whsec_…
// Cuerpo crudo: la firma es sobre los bytes, no sobre el JSON ya leído.
app.post('/ally360/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
const cabecera = req.get('Ally360-Signature') ?? ''
const partes = Object.fromEntries(cabecera.split(',').map((p) => p.split('=')))
const t = Number(partes.t)
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400)
const esperada = crypto.createHmac('sha256', SECRETO).update(`${t}.`).update(req.body).digest('hex')
const valida = partes.v1?.length === esperada.length &&
crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(partes.v1))
if (!valida) return res.sendStatus(400)
const evento = JSON.parse(req.body.toString('utf8'))
// Procesa en segundo plano y responde ya: hay 10 segundos.
res.sendStatus(200)
})import hashlib, hmac, json, os, time
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRETO = os.environ["ALLY360_WEBHOOK_SECRET"].encode() # whsec_…
@app.post("/ally360/webhooks")
async def recibir(request: Request):
cuerpo = await request.body() # bytes crudos
partes = dict(p.split("=", 1) for p in request.headers.get("Ally360-Signature", "").split(",") if "=" in p)
t = int(partes.get("t", 0))
if abs(time.time() - t) > 300:
raise HTTPException(400)
esperada = hmac.new(SECRETO, f"{t}.".encode() + cuerpo, hashlib.sha256).hexdigest()
if not hmac.compare_digest(esperada, partes.get("v1", "")):
raise HTTPException(400)
evento = json.loads(cuerpo)
return {"ok": True}<?php
$secreto = getenv('ALLY360_WEBHOOK_SECRET'); // whsec_…
$cuerpo = file_get_contents('php://input'); // cuerpo crudo
$partes = [];
foreach (explode(',', $_SERVER['HTTP_ALLY360_SIGNATURE'] ?? '') as $par) {
[$k, $v] = array_pad(explode('=', $par, 2), 2, '');
$partes[$k] = $v;
}
$t = (int) ($partes['t'] ?? 0);
if (abs(time() - $t) > 300) { http_response_code(400); exit; }
$esperada = hash_hmac('sha256', $t . '.' . $cuerpo, $secreto);
if (!hash_equals($esperada, $partes['v1'] ?? '')) { http_response_code(400); exit; }
$evento = json_decode($cuerpo, true);
http_response_code(200);Reintentos
Una entrega vale si respondes 2xx en menos de 10 segundos; no seguimos redirecciones. Si no, reintentamos a los 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h. Tras tres días fallando sin una sola entrega exitosa, desactivamos el webhook y avisamos a los administradores de la empresa. Desde la app puedes ver cada entrega, probar el webhook y reenviar.
Eventos
| Evento | Cuándo |
|---|---|
| invoice.created | Se creó una factura de venta (incluye borradores). |
| invoice.issued | La factura dejó de ser borrador y ya cuenta como venta. |
| invoice.paid | La factura quedó pagada por completo. |
| invoice.voided | La factura se anuló. |
| invoice.dian_accepted | La DIAN validó la factura electrónica. |
| invoice.dian_rejected | La DIAN rechazó la factura electrónica. |
| credit_note.issued | Se emitió una nota crédito. |
| credit_note.voided | Se anuló una nota crédito. |
| credit_note.dian_accepted | La DIAN validó la nota crédito electrónica. |
| credit_note.dian_rejected | La DIAN rechazó la nota crédito electrónica. |
| payment.received | Se registró un pago de un cliente. |
| payment.voided | Se anuló un pago de un cliente. |
| contact.created | Se creó un contacto. |
| contact.updated | Cambiaron los datos de un contacto. |
| contact.deleted | Se eliminó un contacto. |
| product.created | Se creó un producto o servicio. |
| product.updated | Cambiaron los datos de un producto o servicio. |
| product.deleted | Se eliminó un producto o servicio. |
| quote.accepted | El cliente aceptó una cotización. |
| quote.converted | Una cotización se convirtió en factura. |
| stock.changed | Cambiaron las existencias de uno o más productos. |
| stock.low | Un producto quedó en o por debajo de su mínimo. |
| purchase.received | Llegó mercancía de una compra. |