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

Creates a new webhook configuration for the authenticated user.

Authorizations

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 | nullableOptional

A user-friendly name for the webhook configuration.

Example: Production Transaction Webhook

descriptionstring | 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

401

Unauthorized

application/json

422

Unprocessable.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/webhooks HTTP/1.1
Host: 
Authorization: Bearer JWT
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

Shows the webhook configuration associated with the authenticated account/user.

Authorizations

Responses

200

Successfully retrieved the webhook configuration details.

application/json

401

Unauthorized.

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/webhooks HTTP/1.1
Host: 
Authorization: Bearer JWT
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

Updates the webhook configuration associated with the authenticated user.

Authorizations

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 | nullableOptional

A user-friendly name for the webhook configuration.

Example: Updated Production Webhook

descriptionstring | 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

401

Unauthorized.

application/json

422

Unprocessable.

application/json

put

HTTPcURLJavaScriptPython

PUT /api/v1/webhooks HTTP/1.1
Host: 
Authorization: Bearer JWT
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."
}