Webhooks

Webhooks are HTTP messages that one application automatically sends to another when specific events occur. The Trustap API sends webhooks for events such as receiving a payment for a transaction or delivering a parcel. Use webhooks in your application to learn about the status of a transaction and start your own processes without polling the Trustap API.

You can create, edit, and delete your webhook configuration in your Trustap Dashboard.

• Sandbox Dashboard
• Production Dashboard

Click Create Webhook and enter the following details.

• URL. This is the URL where the Trustap API sends all webhook events. Your endpoint must use a secure https URL.
• Username and Password. Trustap includes your username and password in your webhook request for authentication.

Trustap includes a standard HTTP Basic Authentication header in each webhook request. Set these credentials when creating your webhook configuration in the Trustap Dashboard, and configure your webhook handler to validate them on every incoming request to verify it genuinely originates from Trustap.

To receive webhook events from Trustap, create a webhook handler for your application. Webhook handlers listen for and process incoming HTTP requests sent by a third-party service including a webhook event.

Trustap sends all webhook events associated with your account to this URL as POST requests, so your firewall rules and endpoint handlers should be set up to handle these.

The Trustap API does not automatically retry failed webhook deliveries if your server is offline or returns an error status code. Because network drops or temporary server maintenance can cause your application to miss a webhook event, you should implement a fallback synchronization strategy.

1. Implement a daily cron job or background worker that queries our Get Transaction Endpoint for any active or pending transactions in your database.
2. Before displaying transaction statuses to your users or completing an internal order, execute a live GET request to verify the state on Trustap's servers matches your local database.

The Trustap API supports the following event codes.

The following is an example payload the Trustap API could pass to a webhook endpoint.

{
  "code": "tx.paid",
  "user_id": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
  "target_id": "tx_01kq9gj63sf4pbpesq9kna5ysa",
  "target_preview": {
    "buyer": {
      "id": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
      "is_guest": true
    },
    "client_id": "e12c9fe5-bd07-47fd-81ec-263b6aaac8d6",
    "deadlines": {
      "complaints": null
    },
    "description": "v2 Payment",
    "events": {
      "by_key": {
        "created": "2026-04-28T07:41:21Z",
        "joined": "2026-04-28T07:41:21Z",
        "paid": "2026-04-28T07:41:25Z"
      },
      "by_time": [
        {
          "at": "2026-04-28T07:41:21Z",
          "code": "created"
        },
        {
          "at": "2026-04-28T07:41:21Z",
          "code": "joined"
        },
        {
          "at": "2026-04-28T07:41:25Z",
          "by": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
          "code": "paid"
        }
      ]
    },
    "id": "tx_01kq9gj63sf4pbpesq9kna5ysa",
    "pricing": {
      "amount": 1000,
      "amount_extra": 0,
      "currency": "eur",
      "fees": {
        "buyer": 50,
        "buyer_client": 0,
        "seller": 0,
        "seller_client": 0
      }
    },
    "seller": {
      "id": "1-e2f0d161-41c7-429d-8cee-7e524e61756f",
      "is_guest": true
    },
    "status": "paid"
  },
  "time": "2026-04-28T07:41:25.213691597Z",
  "metadata": {}
}

The following fields may be included in a webhook payload.

To test your webhook listener, use the following tool to create a sample webhooks event.

1. Enter your Webhook listener URL, optional auth, and select your Sample payload.
2. Copy, paste, and run the generated cURL command in your local terminal to send the sample payload to your webhook listener.