> For the complete documentation index, see [llms.txt](https://aa.docs.rechtlogisch.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aa.docs.rechtlogisch.de/rest-api/webhook.md).

# Webhook

## General

After the successful transmission and delivery of the tax data to the tax authorities, the PDF transfer protocol (as a base64-encoded string) can be automatically passed together with the official transfer ticket to a defined endpoint.

{% hint style="info" %}
The webhook is disabled by default.
{% endhint %}

## Enabling

Set the following environment variable in `docker-compose.yml`

```yaml
HOOK_ENABLED: true
```

## Endpoint

The URI can be adjusted as needed:

```yaml
HOOK_URI: https://target.tld/hook-endpoint
```

## Example endpoint

For testing an example endpoint is provided within the solution

{% hint style="info" %}
The example endpoint processes the received data in-memory. Only the transmitted base64-encoded string is decoded and saved.
{% endhint %}

## hook-endpoint

<mark style="color:green;">`POST`</mark> `http://deric:8080/dummy/hook-endpoint`

Example endpoint for accepting the notification of the successful transmission of the tax data to the tax authorities.

#### Query Parameters

| Name         | Type   | Description      |
| ------------ | ------ | ---------------- |
| Content-Type | string | application/json |

#### Request Body

| Name             | Type    | Description                                    |
| ---------------- | ------- | ---------------------------------------------- |
| ticket           | string  | Ticket ID                                      |
| transfer\_ticket | string  | Transfer Ticket (generated by tax authorities) |
| file\_name       | string  | File name                                      |
| file\_content    | string  | base64-encoded content of the file             |
| store            | boolean | true (default) - store the file                |

{% tabs %}
{% tab title="200 Erwartete Rückmeldung.Wenn success = true und data.received = true nimmt der Webhook an, dass die Daten am Endpunkt angekommen und angenommen wurden.Nur success und data.received werden geprüft." %}

```javascript
{
    "success": true,
    "code": 0,
    "locale": "de",
    "message": "OK",
    "data": {
        "received": true,
        "stored": true,
        "ticket": "12345678",
        "transfer_ticket": "et123456789012345678901234567890",
        "file_name": "dummy_1234567890.txt",
        "file_content": true
    }
}
```

{% endtab %}
{% endtabs %}

## hook-run

<mark style="color:blue;">`GET`</mark> `http://deric:8080/dummy/hook-run/:id`

Test call to notify a provided endpoint with data for the selected ticket.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | Ticket ID   |

{% tabs %}
{% tab title="200 Successful call with data to webhook endpoint, when success = true und data.sent = true." %}

```javascript
{
    "success": true,
    "code": 0,
    "locale": "de",
    "message": "OK",
    "data": {
        "sent": true
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The webhook calls are also stored in [Postman](/rest-api/postman.md).
{% endhint %}