Receive a provider webhook
Accepts a settlement event pushed by the payment provider, persists it verbatim and returns 202 only after that persistence succeeds. Under multi-tenancy, if the resolved tenant’s storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with a secret agreed with the provider, not the platform identity used by the rest of this API. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint’s logs, so that a delivery can be matched against the provider’s own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider’s own webhook test emits and which belongs to no entity’s event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted.
Headers
HMAC-SHA256 of the raw request body under the secret agreed with the provider, lowercase hex. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error.
Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature.
Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides.
Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted.
Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted.
Optional provider correlation identifier. Persisted with the event when present.
Body
Provider entity name the event belongs to, for example PaymentSlipPay or TaxDarfPayment. Cross-checked against x-webhook-baas-entity; the body wins.
Provider-assigned primary key of the entity this event is about. A string representation of a GUID in every delivery seen so far, but not validated as one: the field is the provider's to shape.
Provider state the entity moved to, for example PAID. This IS the provider's event name — the x-webhook-baas-event header carries the same value — and it is stored as sent.
Identifier this service sent when it created the entity, echoed back for correlation. Optional here even though the provider envelope declares it required.
Instant the provider recorded for this state, RFC 3339. Optional here: a delivery without one means no reference instant, not a malformed request.
Response
Accepted