Webhooks delivery

Subscribe to events, verify signatures, and handle retries reliably.

Safepay webhooks notify you when payments, refunds, or settlements change state. Use this guide to create webhook endpoints, verify signatures, and process retries safely.

Create a webhook endpoint

1. Choose the events you need

   Subscribe to the specific event types your integration depends on, such as payment.completed or refund.completed.

2. Create the webhook

   Call POST /v1/aggregators/{{aggregator_id}}/webhooks with the URL and event list.

3. Store the webhook secret

   Safepay returns a webhook secret. Store it in your secret manager and use it for signature verification.

cURL

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/webhooks" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://api.example.com/webhooks/safepay",
    "description": "Raast webhook endpoint",
    "event_types": ["payment.created", "payment.completed", "refund.completed"],
    "enabled": true
  }'

Webhook headers

Safepay includes headers that identify the event and allow you to verify authenticity. Always read:

• X-SFPY-SIGNATURE for the HMAC signature
• X-SFPY-TIMESTAMP for the event timestamp

The delivery also includes headers for event ID, event type, and aggregator ID.

Signature verification

Safepay signs the raw payload body. Use the signature header and timestamp header to verify authenticity.

1. Extract headers

   Read X-SFPY-SIGNATURE and X-SFPY-TIMESTAMP from the incoming request.

2. Compute HMAC

   Compute HMAC SHA-256 using the timestamp, a period separator, and the raw payload bytes: timestamp + '.' + payload.

3. Compare signatures

   Compare the computed signature to the provided signature using a constant-time compare.

func Verify(secret, body []byte, providedSig, providedTS string, tolerance time.Duration) error {
	if tolerance > 0 {
		parsed, err := time.Parse(time.RFC3339Nano, providedTS)
		if err != nil {
			return err
		}
		if delta := time.Since(parsed); delta > tolerance || delta < -tolerance {
			return errTimestampDrift
		}
	}
	mac := hmac.New(sha256.New, secret)
	mac.Write([]byte(providedTS))
	mac.Write([]byte{'.'})
	mac.Write(body)
	expected := fmt.Sprintf(headerFormat, hex.EncodeToString(mac.Sum(nil)))
	if !hmac.Equal([]byte(expected), []byte(providedSig)) {
		return errSignatureMismatch
	}
	return nil
}

Use the webhook payload object as the body argument when computing the signature.

headerFormat represents the signature format Safepay uses when building the X-SFPY-SIGNATURE header. Keep it consistent with the value you receive.

Retry behavior

Safepay retries failed deliveries up to 5 attempts using exponential backoff:

• Attempt 1: 1 second
• Attempt 2: 2 seconds
• Attempt 3: 4 seconds
• Attempt 4: 8 seconds
• Attempt 5: 16 seconds

Respond with 200 OK as soon as you persist the event to stop further retries.

Event catalog

Event	Category	Description
payment.created	Payments	A new payment request was created (initiated by customer).
payment.pending_authorization	Payments	Payment is awaiting authorization (for example, Pay Later checks).
payment.authorized	Payments	Payment has been authorized and funds are on hold.
payment.completed	Payments	Payment has been captured or charged successfully.
payment.settled	Payments	Payment funds have been settled to the merchant.
payment.refunded	Payments	Payment was fully refunded.
payment.refund_partial	Payments	Payment was partially refunded.
payment.rejected	Payments	Payment was rejected before authorization.
payment.failed	Payments	Payment processing failed.
payment.reversed	Payments	Payment was reversed after completion.
payment.voided	Payments	Payment authorization was voided.
settlement.created	Settlements	Settlement request was created.
settlement.processing	Settlements	Settlement is currently processing.
settlement.completed	Settlements	Settlement completed successfully.
settlement.failed	Settlements	Settlement failed during processing.
settlement.on_hold	Settlements	Settlement temporarily placed on hold.
settlement.reversed	Settlements	Settlement was reversed.
refund.created	Refunds	Refund request was created.
refund.completed	Refunds	Refund was successfully completed.
refund.failed	Refunds	Refund failed during processing.
refund.canceled	Refunds	Refund request was canceled.

See also

• Webhooks
• Payment lifecycle guide
• Payout lifecycle
• Errors
• Pagination