# 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.

{% hint style="warning" %}
You must include your **Bearer token** in the request header.
{% endhint %}

## Create webhook configuration

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

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"API.Requests.CreateWebhookRequest":{"title":"Create Webhook Request Body","description":"Data required to create a new webhook configuration.","required":["url","token"],"properties":{"url":{"description":"The target URL endpoint for the webhook messages.","type":"string","format":"url","maxLength":255},"token":{"description":"A secret token sent with webhook messages for verification (e.g., in an 'Authorization' or custom header). Min 16, Max 100 characters.","type":"string","format":"password","maxLength":100,"minLength":16},"name":{"description":"A user-friendly name for the webhook configuration.","type":"string","maxLength":255,"nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","maxLength":500,"nullable":true}},"type":"object"},"API.Resources.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","nullable":true}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create webhook configuration","description":"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.","operationId":"API.Webhooks.Create","requestBody":{"description":"Webhook details necessary to create a transaction","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.CreateWebhookRequest"}}}},"responses":{"201":{"description":"Webhook configuration created successfully. Returns the created resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Show current webhook configuration

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

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"API.Resources.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","nullable":true}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"Show current webhook configuration","description":"Shows the webhook configuration associated with the authenticated account/user. This configuration is used for outbound account, transaction, and virtual IBAN status-change events.","operationId":"API.Webhooks.Show","responses":{"200":{"description":"Successfully retrieved the webhook configuration details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}}
```

## Update current webhook configuration

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

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"API.Requests.UpdateWebhookRequest":{"title":"Update Webhook Request Body","description":"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).","required":["is_active","url","token"],"properties":{"is_active":{"description":"Whether the webhook subscription should be active.","type":"boolean"},"url":{"description":"The target URL endpoint for the webhook messages.","type":"string","format":"url","maxLength":255},"token":{"description":"A secret token sent with webhook messages for verification. Min 16, Max 100 characters.","type":"string","format":"password","maxLength":100,"minLength":16},"name":{"description":"A user-friendly name for the webhook configuration.","type":"string","maxLength":255,"nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","maxLength":500,"nullable":true}},"type":"object"},"API.Resources.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","nullable":true}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/webhooks":{"put":{"tags":["Webhooks"],"summary":"Update current webhook configuration","description":"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.","operationId":"API.Webhooks.Update","requestBody":{"description":"Webhook details necessary to update a transaction","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook configuration updated successfully. Returns the updated resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.gurupay.eu/api-reference/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.