Webhooks
You may register one HTTPS URL. Enovipay POSTs JSON events to it.
| Method | Path | Purpose |
|---|---|---|
PUT | /v1/webhook | Create or replace { "url": "https://…", "enabled": true } |
GET | /v1/webhook | Current URL and status. Never the signing secret |
DELETE | /v1/webhook | Disable the endpoint |
GET | /v1/webhook/deliveries | Recent attempts, paged |
POST | /v1/webhook/deliveries/:id/replay | Retry 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
type | When | Main data fields |
|---|---|---|
payout.submitted, payout.executed, payout.failed, payout.returned | Payout status | payoutRequestId, providerTransactionId, status, amount, currency, externalReference, customer. Failed and returned add failureReason when the partner gave one |
transaction.incoming | Inbound credit settled | transactionId, accountId, providerTransactionId, direction, amount, currency, remitterName, externalReference, timestamp, matchStatus, depositId, customer |
deposit.expired | A declaration ended without a payment, or its customer was changed or deleted | depositId, 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
transaction.incomingmatchStatus 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
deposit.expiredreason 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
Enovipay-Signaturev1 is hex HMAC-SHA256 of `${t}.${rawBody}` using your signingSecret.
- Read the raw body bytes before JSON parse.
- Parse
tandv1fromEnovipay-Signature(t=<unix>,v1=<hex>). - Reject a
tmore than about 5 minutes from your clock. - 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" } }.
| Query | Default | Description |
|---|---|---|
limit | 10 | Page size (minimum 1, maximum 100) |
offset | 0 | Rows 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.
Updated 4 days ago
