Webhooks

When certain events occur, our system sends an HTTPS-request to one or more URLs specified by you up front. These events occur for example when an order is completed for asynchronous usage requests as well as when a product is updated. Events may occur for a variety of scopes and the webhooks will be delivered to you based on the specific subscription.

The webhook requests are all executed with the HTTP method POST with a JSON body. The body contains information about the event that happened, the event scope, a unique webhook ID to allow easy handling of webhook retries, when the event happened, as well as a data object, where the content may differ based on the event scope.

Webhook requests are signed in the same way as requests to the API. For hook requests, we provide the signature in the Fp-Signature header. The signature works as authentication, so always verify the signature to prevent unauthorized access. See Authentication for more information about the signature.

We verify the HTTPS server certificate when making webhook requests to your system, so make sure you have a server certificate accepted by common browsers.

Configuring Webhooks

Webhook subscriptions are managed in the finperks Control Center. A subscription is bound to an API key and consists of the target URL on your system and the event scopes and events you want to receive. Subscriptions are configured separately for the live and sandbox environments, so you can test your webhook handling in the sandbox first.

Event Scopes

Scope	Events	Availability
orders	processing, completed, failed, invalidated, refunded	Always
products	created, updated	Always
settlements	created, paid	Live only — settlements do not exist in the sandbox
client_partners	created, updated, approved, rejected, revoked	Only with client partner tracking enabled

The data object of the webhook payload contains the affected entity in the same representation as the corresponding API endpoint returns it.

Processing Webhooks

• Respond quickly with a 2xx status. Acknowledge the webhook as soon as you have durably received it and do any heavier processing asynchronously afterwards. Requests that take too long to respond are treated as failed.
• Handle duplicates. Since failed deliveries are retried, you may receive the same webhook more than once. The id field stays the same across retries, so you can use it to deduplicate.
• Do not rely on ordering. Events are usually delivered in order, but retries can cause events to arrive late or out of order. Rely on the entity state in the data object, and when in doubt retrieve the current state from the API, e.g. via GET /orders/{id}.

Failed Requests

If a webhook request fails, we retry the request multiple times. The waiting time between retries increases with each attempt to ensure that your server is not overloaded. Deliveries are retried over an extended period (more than a day in total), so shorter outages of your endpoint do not lead to lost events. After the final attempt, the webhook is not delivered — make sure to reconcile via the API after longer outages, e.g. by polling the affected resources.

We regard all HTTP status codes in the 2xx range as success and everything else as an error. This means redirect status codes like 307 are interpreted as error since we do not follow redirects.