Skip to main content
Raast is asynchronous: customers approve or reject requests inside their banking apps, and Safepay pushes the resulting status to your backend via webhooks. Subscribe to these notifications to drive real-time UI updates and back-office automations.

​
Webhook flow

1

Create a webhook endpoint

Use POST /v1/aggregators/{{aggregator_id}}/webhooks with the event types you want.
2

Receive the event

Safepay sends events with identifying headers, the event timestamp, and a signed payload.
3

Verify and acknowledge

Verify the signature, persist the payload, and respond with 200 OK.

​
Headers

Safepay includes headers for event ID, event type, aggregator ID, signature, and timestamp. Always read:
  • X-SFPY-SIGNATURE
  • X-SFPY-TIMESTAMP
Use the event ID header for idempotency and safe retries.

​
Signature verification

Safepay signs the raw payload body with HMAC SHA-256 using timestamp + '.' + payload. Use the webhook secret you receive when creating the webhook. 
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

​
Event catalog

EventCategoryDescription
payment.createdPaymentsA new payment request was created (initiated by customer).
payment.pending_authorizationPaymentsPayment is awaiting authorization (for example, Pay Later checks).
payment.authorizedPaymentsPayment has been authorized and funds are on hold.
payment.completedPaymentsPayment has been captured or charged successfully.
payment.settledPaymentsPayment funds have been settled to the merchant.
payment.refundedPaymentsPayment was fully refunded.
payment.refund_partialPaymentsPayment was partially refunded.
payment.rejectedPaymentsPayment was rejected before authorization.
payment.failedPaymentsPayment processing failed.
payment.reversedPaymentsPayment was reversed after completion.
payment.voidedPaymentsPayment authorization was voided.
settlement.createdSettlementsSettlement request was created.
settlement.processingSettlementsSettlement is currently processing.
settlement.completedSettlementsSettlement completed successfully.
settlement.failedSettlementsSettlement failed during processing.
settlement.on_holdSettlementsSettlement temporarily placed on hold.
settlement.reversedSettlementsSettlement was reversed.
refund.createdRefundsRefund request was created.
refund.completedRefundsRefund was successfully completed.
refund.failedRefundsRefund failed during processing.
refund.canceledRefundsRefund request was canceled.

​
Key endpoints

EndpointPurpose
POST /v1/aggregators/{{aggregator_id}}/webhooksCreate a webhook.
GET /v1/aggregators/{{aggregator_id}}/webhooksList webhook endpoints.
GET /v1/aggregators/{{aggregator_id}}/webhooks/{{webhook_id}}Read a webhook endpoint.
PUT /v1/aggregators/{{aggregator_id}}/webhooks/{{webhook_id}}Update a webhook endpoint.
DELETE /v1/aggregators/{{aggregator_id}}/webhooks/{{webhook_id}}Delete a webhook endpoint.
PUT /v1/aggregators/{{aggregator_id}}/webhooks/{{webhook_id}}/rotateRotate the webhook secret.
GET /v1/aggregators/{{aggregator_id}}/webhooks/{{endpoint}}/deliveriesList webhook deliveries.
GET /v1/aggregators/{{aggregator_id}}/webhooks/{{endpoint}}/deliveries/{{delivery}}Read a webhook delivery.

​
See also