Payment webhooks - Onboarding guide

This guide explains how to start receiving payment webhooks from Kivra. Payment webhooks notify you in real time when payment events occur (e.g. scheduled, settled, or failed).

API reference - payment webhooks

Step 1 - Prerequisites

Before you begin:

  • You must have an active sending agreement with Kivra (directly or via a partner).
  • Depending on your current agreement, you may need to sign an updated Terms of Service and Data Processing Agreement.
  • You need an endpoint (HTTPS) capable of receiving webhook POST requests and responding within 1 second with a 200 status code.

Step 2 - Decide Your Onboarding Path

How you integrate with Kivra determines how webhooks are set up:

  • Via a partner, webhooks handled by partner → No setup needed with Kivra. Contact your partner for details.
  • Direct sender (you send content directly to Kivra) → Use Self-service onboarding.
  • Via a partner, but you want webhooks directly from Kivra → Use Manual onboarding.

Step 3 - Provide Your Webhook Details

Self-service onboarding

Use your existing sending credentials to register a webhook definition via API:

  • Provide your webhook URL (must be HTTPS).
  • Choose which payment types (instant, bank, autogiro) and events (scheduled, settled, failed) you want to subscribe to.
  • Instructions: Kivra API docs .

You can also use the API to:

  • List existing webhook definitions.
  • Modify or remove definitions.
  • Request test deliveries with mock payloads.

Note! In order to activate the service: contact avsandare.support@kivra.com and request to allow webhook activation.

Manual onboarding

If Kivra needs to configure your webhook, please send the following to your Kivra contact:

  • Your tenant key (Kivra provides this if you don’t already know it).
  • Your webhook URL.
  • The events you want to receive (see Kivra API docs ).
  • The email address and phone number for delivery of credentials.

Kivra will:

  1. Configure your webhook definition.
  2. Validate that your endpoint is ready.
  3. Confirm activation.

Step 4 - Webhook Delivery & Security

  • Kivra signs each webhook with an HMAC signature. Use the headers (webhook-id, webhook-timestamp, webhook-signature) to verify authenticity.
  • Retries follow a standard backoff schedule (up to 10 attempts over ~75 hours).
  • Your system must respond with 2xx within 1 second to avoid retries.

Step 5 - You’re Live

Once activated, you will receive webhook notifications for payment events in real time.

Suggested next step: test your integration by requesting a test delivery via API before going live.

Har du feedback? Hör gärna av dig!
Skicka feedback