Skip to main content
    ArosaPay
    Start application

    Docs · Webhooks

    Signed events for status, dispute, and settlement changes.

    Every ArosaPay webhook is signed, timestamped, and carries a unique event id — verify the signature, reject stale timestamps, and deduplicate on event id.

    API referenceSDK reference

    Envelope

    type

    The event type. Examples: transaction.reserved, transaction.safeguarded, transaction.delivered, transaction.confirmed, transaction.released, transaction.refunded, dispute.opened, dispute.resolved.

    id

    The unique event id. Also delivered as X-ArosaPay-Event-Id — use for deduplication.

    created

    Event creation time (unix seconds). Also delivered as X-ArosaPay-Timestamp.

    data

    Event payload — includes merchant_reference, merchant_order_id, arosapay_transaction_id, and the current settlement_status.

    Headers

    X-ArosaPay-Signature

    HMAC-SHA256 of `${timestamp}.${body}` with your webhook secret.

    X-ArosaPay-Timestamp

    Unix seconds. Reject events older than 300 seconds.

    X-ArosaPay-Event-Id

    Unique per event. Persist and skip duplicates.

    Verification checklist

    1. 01
      Parse timestamp

      Reject if abs(now − timestamp) > 300 seconds.

    2. 02
      Recompute signature

      HMAC-SHA256 with your webhook secret, compare in constant time.

    3. 03
      Deduplicate

      Store event ids you have already processed. Skip repeats.

    4. 04
      Respond 2xx

      Return within 5 seconds. Non-2xx responses are retried with exponential backoff.

    Retries

    Delivery is at-least-once.

    Non-2xx responses are retried with exponential backoff for up to 24 hours. Deduplicate on event id.

    Reconciliation