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:

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/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/1.1 200 OK
Content-Length: 0

Example 3: Validate some commands and retry unfinished work

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

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

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

Example 4: Specify a delivery 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.

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"
        }
      ]
    }
  ]
}