Skip to main content
Pagsmile uses at-least-once delivery. A webhook can arrive more than once, and events are not guaranteed to arrive in business-time order.

​
Successful Acknowledgement

A delivery is acknowledged only when your server returns a final HTTP 200 response.
  • Non-200 Statuses: Responses like 201, 202, 204, 4xx, 5xx, or network timeouts are evaluated as failures.
  • Redirects (3xx): KYB and MED deliveries do not follow redirects; any 3xx response is a failed acknowledgement. Register the final callback URL directly.
  • Response Body: The HTTP response body is ignored when determining delivery success.
To prevent timeouts and handle delivery guarantees effectively, follow this sequence in your receiver:
1

Read Raw Bytes

Read the raw HTTP request body from the network stream.
2

Verify Authenticity

Validate the HMAC signature (X-Signature) and replay controls (X-Nonce).
3

Validate Minimum Fields

Ensure required payload fields are present.
4

Atomically Store Record

Insert the idempotency key and raw event into your database.
5

Acknowledge Fast (HTTP 200)

Return HTTP 200 immediately to acknowledge delivery.
6

Process Asynchronously

Execute slower downstream business logic using background queues/workers.

​
Delivery Identifiers & Idempotency Keys

Different webhook scopes provide different delivery identifiers:
Scope / FamilyIdentifier TypeRecommended Idempotency Key
Transaction (USER)Stable delivery_iddelivery_id
Transaction (ACCOUNT)No delivery_idtxn_id + configured_event_type
KYB (USER & PLATFORM)Stable delivery_iddelivery_id
MED (USER & ACCOUNT)Stable delivery_iddelivery_id
If a duplicate event arrives after your system has already processed it, return HTTP 200 immediately after recognizing the key.

​
HTTP Retry Schedule

When a delivery attempt fails, Pagsmile schedules up to 8 total attempts (initial attempt + 7 retries):

Retry 1

5 seconds

Retry 2

10 seconds

Retry 3

20 seconds

Retry 4

30 seconds

Retry 5

60 seconds (1m)

Retry 6

120 seconds (2m)

Retry 7

240 seconds (4m)

​
Receiver Best Practices Checklist

  • Make processing idempotent: Always deduplicate incoming requests using stable keys.
  • Do not assume global ordering: Events may arrive out of order.
  • Preserve raw events: Store the raw payload for audit and reconciliation purposes.
  • Respond quickly: Avoid executing heavy database transactions before returning HTTP 200.
  • Monitor metrics: Track latency, non-200 response rates, and signature validation failures.