Ctrlk
DashboardSandbox Dashboard
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks

Webhooks allow your system to receive real-time notifications from Guru Pay when specific events occur (transaction processing completed, new transaction is created, etc.). You can manage your webhook configuration using the following endpoints.

You must include your Bearer token in the request header.

Create webhook configuration

post
/api/v1/webhooks

Creates a new webhook configuration for the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events.

Authorizations
AuthorizationstringRequired

Authentication using a Bearer token.

Body

Data required to create a new webhook configuration.

urlstring · url · max: 255Required

The target URL endpoint for the webhook messages.

Example: https://example.com/my-webhook-listener
tokenstring · password · min: 16 · max: 100Required

A secret token sent with webhook messages for verification (e.g., in an 'Authorization' or custom header). Min 16, Max 100 characters.

Example: whsec_aBcDeFgHiJkLmNoPqRsTuV
namestring · max: 255 · nullableOptional

A user-friendly name for the webhook configuration.

Example: Production Transaction Webhook
descriptionstring · max: 500 · nullableOptional

An optional description for the webhook configuration.

Example: Notifies the main system about new transactions.
Responses
201

Webhook configuration created successfully. Returns the created resource.

application/json

Resource representing a configured webhook subscription.

uuidstring · uuidOptional

Unique identifier for the webhook configuration.

Example: b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e
is_activebooleanOptional

Indicates whether the webhook subscription is currently active and sending events.

Example: true
urlstring · urlOptional

The URL endpoint where webhook messages will be delivered.

Example: https://example.com/webhooks/receiver
tokenstringOptional

The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.

Example: whsec_...masked...
namestring · nullableOptional

A user-defined name for the webhook configuration.

Example: My Transaction Notifier
descriptionstring · nullableOptional

An optional description for the webhook configuration.

Example: Sends notifications for completed SEPA transactions.
post/api/v1/webhooks
POST /api/v1/webhooks HTTP/1.1
Host: public-api.gurupay.eu
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 193

{
  "url": "https://example.com/my-webhook-listener",
  "token": "whsec_aBcDeFgHiJkLmNoPqRsTuV",
  "name": "Production Transaction Webhook",
  "description": "Notifies the main system about new transactions."
}
{
  "uuid": "b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e",
  "is_active": true,
  "url": "https://example.com/webhooks/receiver",
  "token": "whsec_...masked...",
  "name": "My Transaction Notifier",
  "description": "Sends notifications for completed SEPA transactions."
}

Show current webhook configuration

get
/api/v1/webhooks

Shows the webhook configuration associated with the authenticated account/user. This configuration is used for outbound account, transaction, and virtual IBAN status-change events.

Authorizations
AuthorizationstringRequired

Authentication using a Bearer token.

Responses
200

Successfully retrieved the webhook configuration details.

application/json

Resource representing a configured webhook subscription.

uuidstring · uuidOptional

Unique identifier for the webhook configuration.

Example: b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e
is_activebooleanOptional

Indicates whether the webhook subscription is currently active and sending events.

Example: true
urlstring · urlOptional

The URL endpoint where webhook messages will be delivered.

Example: https://example.com/webhooks/receiver
tokenstringOptional

The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.

Example: whsec_...masked...
namestring · nullableOptional

A user-defined name for the webhook configuration.

Example: My Transaction Notifier
descriptionstring · nullableOptional

An optional description for the webhook configuration.

Example: Sends notifications for completed SEPA transactions.
get/api/v1/webhooks
GET /api/v1/webhooks HTTP/1.1
Host: public-api.gurupay.eu
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uuid": "b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e",
  "is_active": true,
  "url": "https://example.com/webhooks/receiver",
  "token": "whsec_...masked...",
  "name": "My Transaction Notifier",
  "description": "Sends notifications for completed SEPA transactions."
}

Update current webhook configuration

put
/api/v1/webhooks

Updates the webhook configuration associated with the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events.

Authorizations
AuthorizationstringRequired

Authentication using a Bearer token.

Body

Data required to update an existing webhook configuration. All fields are typically required for PUT/replace semantics, but PATCH might allow partial updates (adjust schema 'required' if using PATCH).

is_activebooleanRequired

Whether the webhook subscription should be active.

Example: true
urlstring · url · max: 255Required

The target URL endpoint for the webhook messages.

Example: https://example.com/my-updated-webhook-listener
tokenstring · password · min: 16 · max: 100Required

A secret token sent with webhook messages for verification. Min 16, Max 100 characters.

Example: whsec_xYzAbCdEfGhIjKlMnOpQrS
namestring · max: 255 · nullableOptional

A user-friendly name for the webhook configuration.

Example: Updated Production Webhook
descriptionstring · max: 500 · nullableOptional

An optional description for the webhook configuration.

Example: Updated description for the webhook.
Responses
200

Webhook configuration updated successfully. Returns the updated resource.

application/json

Resource representing a configured webhook subscription.

uuidstring · uuidOptional

Unique identifier for the webhook configuration.

Example: b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e
is_activebooleanOptional

Indicates whether the webhook subscription is currently active and sending events.

Example: true
urlstring · urlOptional

The URL endpoint where webhook messages will be delivered.

Example: https://example.com/webhooks/receiver
tokenstringOptional

The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.

Example: whsec_...masked...
namestring · nullableOptional

A user-defined name for the webhook configuration.

Example: My Transaction Notifier
descriptionstring · nullableOptional

An optional description for the webhook configuration.

Example: Sends notifications for completed SEPA transactions.
put/api/v1/webhooks
PUT /api/v1/webhooks HTTP/1.1
Host: public-api.gurupay.eu
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 202

{
  "is_active": true,
  "url": "https://example.com/my-updated-webhook-listener",
  "token": "whsec_xYzAbCdEfGhIjKlMnOpQrS",
  "name": "Updated Production Webhook",
  "description": "Updated description for the webhook."
}
{
  "uuid": "b2e1d0c9-f8a7-4b6a-9c5d-4e3f2a1b0d9e",
  "is_active": true,
  "url": "https://example.com/webhooks/receiver",
  "token": "whsec_...masked...",
  "name": "My Transaction Notifier",
  "description": "Sends notifications for completed SEPA transactions."
}

Response requirements for webhook services

When GuruPay sends a webhook message to the configured url, the customer’s webhook service must respond with HTTP status code 202 Accepted. Otherwise, the delivery attempt may be treated as unsuccessful, and the webhook message will be retried until a successful 202 Accepted response is received.

PreviousTransactions
NextWebhook Messages

Last updated

Was this helpful?