> For the complete documentation index, see [llms.txt](https://docs.tip4serv.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tip4serv.com/webhooks-developers-only/webhook-responses.md).

# Webhook Responses

This guide explains how to respond to Tip4Serv webhooks, report delivery results globally or per server and command, control when payments or subscriptions are marked as processed, and request retries for unfinished work.

### Response Semantics

#### A) `200 OK` with no body

All orders contained in the event are marked as delivered, and the related payment or subscription is marked as processed. This is the global acknowledgment behavior.

#### B) `200 OK` with targeted JSON

Return `Content-Type: application/json; charset=utf-8` to report delivery results per server or command:

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "retry_after": 60,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        { "command_id": "0", "delivered": true },
        {
          "command_id": "1",
          "delivered": false,
          "error": "There was a problem here"
        },
        { "command_id": "2", "pending": true }
      ]
    },
    {
      "server_id": "20861",
      "delivered": true
    }
  ]
}
```

#### Retry Behavior

There are two ways to request a retry:

* Successful response (2xx): include retry\_after in the JSON response body, in seconds. The worker retries only if commands remain unfinished. For a 200 response, the effective delay is at least 60 seconds and may be longer due to the worker’s retry backoff.
* Temporary failure (503 Service Unavailable): include the HTTP Retry-After header. Its value can be a delay in seconds or an HTTP date. The worker retries after that delay. The response body is not used to update command delivery results.

### Usage Examples

#### Example 1: Retry after 120 seconds

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/plain; charset=utf-8

Temporary failure. Please retry later.
```

#### Example 2: Validate everything

```http
HTTP/1.1 200 OK
Content-Length: 0
```

#### Example 3: Validate some commands and retry unfinished work

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "retry_after": 60,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        { "command_id": "0", "delivered": true },
        {
          "command_id": "1",
          "delivered": false,
          "error": "server unreachable"
        }
      ]
    }
  ]
}
```

#### Example 3: Validate an entire server

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "results": [
    { "server_id": "20861", "delivered": true }
  ]
}
```

#### Example 4: Specify a d**elivery date for a command**

To specify when a command was delivered, include an optional `date` on its command result. ISO 8601 timestamps are recommended.

If the date is omitted or invalid, the worker uses the time it processed the response.

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true,
  "results": [
    {
      "server_id": "20859",
      "commands": [
        {
          "command_id": "0",
          "delivered": true,
          "date": "2026-10-07T12:00:00.000Z"
        }
      ]
    }
  ]
}
```