Webhooks

You may register one HTTPS URL. Enovipay POSTs JSON events to it.

MethodPathPurpose
PUT/v1/webhookCreate or replace { "url": "https://…", "enabled": true }
GET/v1/webhookCurrent URL and status. Never the signing secret
DELETE/v1/webhookDisable the endpoint
GET/v1/webhook/deliveriesRecent attempts, paged
POST/v1/webhook/deliveries/:id/replayRetry one delivery. Same event id

PUT returns signingSecret (whsec_…) only when the endpoint is first created or the URL changes. Store it then. GET will not give it back. GET /v1/webhook returns null if you have never registered one.

Setting or replaying the webhook is 403 CONDITION_FAILED unless the credential reads transactions, payouts and deposits with no condition and no withheld field. An unscoped key passes.

Events

typeWhenMain data fields
payout.submitted, payout.executed, payout.failed, payout.returnedPayout statuspayoutRequestId, providerTransactionId, status, amount, currency, externalReference, customer. Failed and returned add failureReason when the partner gave one
transaction.incomingInbound credit settledtransactionId, accountId, providerTransactionId, direction, amount, currency, remitterName, externalReference, timestamp, matchStatus, depositId, customer
deposit.expiredA declaration ended without a payment, or its customer was changed or deleteddepositId, accountId, customer, externalReference, amount, currency, expiresAt, matchableUntil, reason

customer is { "customerId": "…", "customerReference": "…" }, or null when there is neither. accountId on transaction.incoming and deposit.expired is the vIBAN account the payment was for.

transaction.incoming

matchStatus is matched, matched_amount_mismatch or unmatched. depositId is the declaration the payment matched, else null. amount is the amount credited to your account. There is no feeAmount. Compare amount with the declaration, or read matchStatus, to tell a short payment from an exact one. There is no separate event for a short payment.

deposit.expired

reason is expired, rebound or deleted. One event id per declaration, however often it is retried. amount is the amount you declared.

Direct payouts

payoutRequestId and customer are null when the payout was created directly at the provider and has no payout request of yours. That shape is sent only while direct payout events are enabled.

Verify Enovipay-Signature

v1 is hex HMAC-SHA256 of `${t}.${rawBody}` using your signingSecret.

  1. Read the raw body bytes before JSON parse.
  2. Parse t and v1 from Enovipay-Signature (t=<unix>,v1=<hex>).
  3. Reject a t more than about 5 minutes from your clock.
  4. Compare the HMAC in constant time.

Respond 2xx within 10 seconds. Any other status is retried.

Deliveries

GET /v1/webhook/deliveries is newest first, paged: { "data", "meta": { "limit", "offset", "total" } }.

QueryDefaultDescription
limit10Page size (minimum 1, maximum 100)
offset0Rows to skip
status—pending, sending, failed, delivered, or dead_letter (pending / sending both include queued and in-flight rows and both present as pending)
eventType—Filter by event type
createdFrom, createdTo—Inclusive bounds; createdFrom must be ≤ createdTo

Unknown query names or an unknown status are 400. Each row carries attemptCount (not attempt), plus nextAttemptAt, lastHttpStatus, lastError and deliveredAt.

Retries

Delivery is at-least-once: 30s, 2m, 10m, 1h, 6h, six attempts, then dead_letter. Dedupe on id (the same value as Enovipay-Event-Id). A replay reuses that id.

Respond 410 Gone only when this URL is retired forever. That disables the webhook. For a transient error use 5xx or 429.


Did this page help you?