Developer Documentation

Webhooks

Webhooks

Webhook endpoints:

• POST /webhooks/payment-provider
• POST /webhooks/bank
• POST /webhooks/ghipss-partner
• POST /webhooks/{providerCode}

Every webhook must send:

X-Signature: {hex_hmac_sha256}
X-Webhook-Event-ID: {provider-event-id}
Content-Type: application/json

The signature is:

hex_hmac_sha256(raw_request_body, WEBHOOK_SECRET)

SikaaHub stores raw headers, raw payload, provider code, provider event ID, provider reference, event type, signature validity, attempts, and processing status in webhook_events. (provider_code, provider_event_id) is unique to prevent duplicate processing.

Webhook data is only accepted as an external signal. Provider adapters verify signatures and normalize the response before the core system applies any status change.

Provider payment states:

• awaiting_provider
• processing
• provider_success
• successful
• provider_failed
• failed

Successful provider webhooks finalize the payment ledger. Failed provider webhooks mark the payment as provider_failed. Mismatched or invalid webhook events create risk signals for review.

Retries can be queued through:

POST /webhooks/retry/{eventId}