Webhooks firmados

Eventos

Al registrar un destino puedes suscribirte a eventos concretos. El contrato actual incluye mensajes inbound, actualizaciones de estado, pruebas de integración y estados del onboarding.

• message.inbound.received
• message.status.updated
• integration.test
• onboarding.session.completed
• onboarding.session.provisioned
• onboarding.session.failed

Headers de firma

Nuntia firma el string formado por {timestamp}.{raw_body} con HMAC SHA-256 y el secreto configurado para ese webhook.

X-Nuntia-Event: message.status.updated
X-Nuntia-Timestamp: 1783846800
X-Nuntia-Signature: v1=<hex-hmac-sha256>

Verificación

1. Lee el body crudo antes de deserializar JSON.
2. Rechaza timestamps no numéricos o con más de 300 segundos de diferencia.
3. Calcula HMAC SHA-256 sobre timestamp + '.' + body.
4. Anteponle v1= y compara en tiempo constante.
5. Devuelve HTTP 2xx solo cuando el evento quedó aceptado de forma idempotente.

$timestamp = $request->header('X-Nuntia-Timestamp');
$provided = $request->header('X-Nuntia-Signature');
$rawBody = $request->getContent();

abort_if(abs(time() - (int) $timestamp) > 300, 403);

$expected = 'v1='.hash_hmac(
    'sha256',
    $timestamp.'.'.$rawBody,
    config('services.nuntia.callback_secret'),
);

abort_unless(hash_equals($expected, $provided), 403);

Entrega y recuperación

Nuntia registra cada intento y permite consultar callbacks o solicitar un replay elegible. Tu receptor debe usar event_id como llave idempotente: un retry no debe repetir efectos de negocio.

La URL debe usar HTTPS, ser pública y cumplir la política de dominios del workspace. Nuntia valida el destino para evitar callbacks hacia redes internas.