NuevoAlly IA ya responde con las cifras de tu negocioPruébala →

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.

invoice.paid
{
  "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.

Node.js (Express)
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)
})
Python (FastAPI)
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
<?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

EventoCuándo
invoice.createdSe creó una factura de venta (incluye borradores).
invoice.issuedLa factura dejó de ser borrador y ya cuenta como venta.
invoice.paidLa factura quedó pagada por completo.
invoice.voidedLa factura se anuló.
invoice.dian_acceptedLa DIAN validó la factura electrónica.
invoice.dian_rejectedLa DIAN rechazó la factura electrónica.
credit_note.issuedSe emitió una nota crédito.
credit_note.voidedSe anuló una nota crédito.
credit_note.dian_acceptedLa DIAN validó la nota crédito electrónica.
credit_note.dian_rejectedLa DIAN rechazó la nota crédito electrónica.
payment.receivedSe registró un pago de un cliente.
payment.voidedSe anuló un pago de un cliente.
contact.createdSe creó un contacto.
contact.updatedCambiaron los datos de un contacto.
contact.deletedSe eliminó un contacto.
product.createdSe creó un producto o servicio.
product.updatedCambiaron los datos de un producto o servicio.
product.deletedSe eliminó un producto o servicio.
quote.acceptedEl cliente aceptó una cotización.
quote.convertedUna cotización se convirtió en factura.
stock.changedCambiaron las existencias de uno o más productos.
stock.lowUn producto quedó en o por debajo de su mínimo.
purchase.receivedLlegó mercancía de una compra.
¿Tienes dudas?