Static Webhook Endpoints

Static endpoints let you register a webhook URL once at the organization level and receive matching events for every payment, refund, settlement and chargeback — without attaching a webhook_url to each payment. They are configured via the TapTree Dashboard under Entwickler → Webhooks (the merchant dashboard is German). They complement the per-payment webhook_url; both fire in parallel today, so you can migrate without dropping events.

When to use static endpoints

Use static endpoints when:

• You want a single, durable receiver for every event your organization produces.
• You need to receive events that have no per-payment context (settlement closed, chargeback received, organization lifecycle).
• You want to subscribe to specific event types instead of receiving all event types for a payment.
• You want to rotate the signing secret on a schedule without touching every running payment.

Stick with the per-payment webhook_url only if you have a use case for one-off webhook routing that doesn't fit the organization-wide pattern (for example, A/B testing two receivers).

Configure a static endpoint

1. In the TapTree Dashboard go to Entwickler → Webhooks and click "Add endpoint".
2. Enter your HTTPS URL plus a short label.
3. Pick the event types you want to receive. Subscriptions support four wildcard styles:

Subscription	Matches
transactions.payment.paid	exactly this event type
transactions.payment.*	every event under transactions.payment (paid, failed, canceled, ...)
transactions.*	every event under transactions (payments, refunds, chargebacks, ...)
*	every event we emit

4. Save. The dashboard reveals the signing secret exactly once — copy it into your secret manager. We never store the plaintext; if you lose it you must rotate. See Webhook Signing Secrets for the envelope-encryption design and the rationale behind one-shot reveal.

Verify the v2 signature (signature-algo: hmac-sha256-v2) before acting on any payload — see Webhook Testing for runnable Node, Python, PHP and Ruby snippets plus a going-live runbook, or Verifying Signatures for the inline overview.

Signing-secret rotation

Click "Rotate secret" on an endpoint to mint a new version. The previous version stays valid for a 24h grace period so an in-flight delivery cannot be dropped mid-rotation. Your server must accept signatures from either version during the overlap window; verify against the newest first and fall back to the previous one only if the newest fails.

Rotate immediately if you suspect the secret has been compromised, otherwise schedule rotations as part of your normal secret hygiene. The signature-secret-id header tells you which version of the secret signed each event. Full rotation flow and the matching verifier behaviour are documented in Webhook Signing Secrets.

Per-environment endpoints

Each endpoint is scoped to exactly one environment — Live or Test. Events from a test payment will never reach a live endpoint. Configure a test endpoint pointing at your staging integration and a live endpoint pointing at production. The Dashboard's environment switcher above the list controls which set you see.

If you need the same URL to receive both, create two endpoints with the same url (one per environment). The mode field inside the event body indicates which environment produced it.

Per-acceptor scoping (optional)

An acceptor is the sub-account that owns the merchant relationship for a given payment (see Acceptors). By default an endpoint receives events for every acceptor in your organization. If you operate multiple acceptors and want to route events to different receivers, you can scope an endpoint to a single acceptor at create time. Once set, this scope is immutable — to change it, delete the endpoint and create a new one.

Event-type subscriptions

The subscription wildcards available at create time are documented in the Configure step 3 table above. Subscriptions are validated against the live event catalog at create time and the Dashboard surfaces the catalog as autocomplete suggestions.

URL requirements

• Must be HTTPS (http:// is rejected at create time).
• Must be publicly reachable — private IP space, link-local addresses and cloud metadata endpoints are blocked.
• Must respond to POST with 2xx within 30 seconds. Non-2xx or timeouts mark the delivery as failed and we retry with exponential backoff.

Lifecycle

An endpoint goes through these states:

Capacity

You can register up to 50 endpoints per environment per organization. If you hit the cap, delete unused endpoints first. Endpoints that have been soft-deleted do not count against the limit.

Audit log

Every change to an endpoint — creation, update, secret reveal, secret rotation, state transition — is recorded in a per-organization tamper-evident audit log. Open an endpoint's Audit-Log from its row menu in the Dashboard to inspect the history. Each entry is cryptographically chained to the previous one; we continuously validate the chain and any tampering is detected.

The audit log retention follows the PCI DSS 10.5.1 requirement.

Delivery guarantees

We deliver every event at least once. Plan for duplicates: dedupe on the event id field, which is unique per event. Retries use exponential backoff for up to 46 hours, after which the delivery is marked as failed. Test and live endpoints use the same retry schedule. After repeated failures, the circuit breaker opens and the endpoint is auto-disabled (see lifecycle).

For ordering, treat events as independent — we do not guarantee delivery order, especially across endpoints. Use triggered_at on the event body to reconstruct timelines on your side.