API Reference

Webhook endpoints

Registrá URLs donde Argentive Card te POSTea eventos firmados. Ver el contrato completo de webhooks (eventos, firma HMAC y best practices) para los detalles del envelope y verificación.

El objeto WebhookEndpoint

ejemplo
{
  "id":            "whe_01HW3FN8XK4MNQ...",
  "url":           "https://miapp.com/api/webhooks/argentive",
  "enabledEvents": ["card.*", "transaction.cleared", "balance.low"],
  "status":        "active",
  "secret":        null,
  "lastResponseStatus": 200,
  "lastDeliveredAt": "2026-06-24T11:53:21Z",
  "failureCount":  0,
  "createdAt":     "2026-06-24T11:30:00Z"
}
Atención
El campo secret solo se devuelve UNA vez, en la respuesta del POST de creación. Después se accede vía POST /:id/reveal_secret (auditado).

Crear un endpoint

POST/api/v1/webhook_endpoints
Body
urlrequired
string
URL HTTPS pública donde Argentive postea los eventos. HTTP queda bloqueado en producción.
enabledEventsrequired
string[]
Lista de event types o wildcards. Ej ["card.*","transaction.cleared"]. Ver lista completa.
description
string
Label interno. No vuelve al webhook.
metadata
object
Hasta 5 KV propios.
curl
curl -X POST "$ARGENTIVE_BASE/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":           "https://miapp.com/api/webhooks/argentive",
    "enabledEvents": ["card.*", "transaction.*", "balance.low"],
    "description":   "Producción — backend principal"
  }'
response — 201 (secret visible)
{
  "id":            "whe_01HW3FN8XK4MNQ...",
  "url":           "https://miapp.com/api/webhooks/argentive",
  "enabledEvents": ["card.*", "transaction.*", "balance.low"],
  "secret":        "whsec_4242abcdef0123456789...",
  "status":        "active",
  "createdAt":     "2026-06-24T11:30:00Z"
}

Listar endpoints

GET/api/v1/webhook_endpoints

Obtener un endpoint

GET/api/v1/webhook_endpoints/:id

Actualizar

PATCH/api/v1/webhook_endpoints/:id
curl
curl -X PATCH "$ARGENTIVE_BASE/api/v1/webhook_endpoints/whe_01HW3..." \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabledEvents": ["card.*", "transaction.cleared", "transaction.declined"]
  }'

Eliminar

DELETE/api/v1/webhook_endpoints/:id

Rotar el secret

POST/api/v1/webhook_endpoints/:id/roll_secret

Genera un nuevo secret. El anterior sigue válido por 1 hora para que actualices tu deploy sin downtime de webhooks. Auditado.

response
{
  "id":             "whe_01HW3FN8XK4MNQ...",
  "newSecret":      "whsec_4242newabcdef...",
  "previousValidUntil": "2026-06-24T12:53:21Z"
}

Mostrar el secret actual (auditado)

POST/api/v1/webhook_endpoints/:id/reveal_secret

Si perdiste el secret originalmente entregado en el POST de creación, podés revelarlo otra vez con este endpoint. Cada acceso queda auditado.

Disparar un evento de prueba

POST/api/v1/webhook_endpoints/:id/send_test
Body
event_typerequired
string
card.created · card.closed · transaction.cleared · balance.low
Tipo de evento a simular.
curl
curl -X POST \
  "$ARGENTIVE_BASE/api/v1/webhook_endpoints/whe_01HW3.../send_test" \
  -H "Authorization: Bearer $ARGENTIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "transaction.cleared" }'

# { "delivered": true, "evtId": "evt_test_01HW3..." }

Logs de entrega

GET/api/v1/webhook_endpoints/:id/deliveries

Histórico de los últimos 30 días de intentos de entrega — útil para debuggear endpoints que fallan.

response
{
  "deliveries": [
    {
      "id":            "del_01HW3FN9...",
      "evtId":         "evt_01HW3FN9...",
      "eventType":     "transaction.cleared",
      "responseStatus": 200,
      "durationMs":    43,
      "attemptedAt":   "2026-06-24T11:53:21Z"
    },
    {
      "id":            "del_01HW3FN8...",
      "evtId":         "evt_01HW3FN8...",
      "eventType":     "card.closed",
      "responseStatus": 502,
      "durationMs":    9870,
      "attemptedAt":   "2026-06-24T11:53:11Z",
      "nextRetryAt":   "2026-06-24T11:54:11Z"
    }
  ]
}