Notification endpoints and API keys

Two credentials complete onboarding: a notification endpoint with its own signing secret, where Tekmerion delivers payment_finalized and related notifications, and a merchant API key, which authenticates your calls to the API. This page covers registering both.

Notification endpoints

A notification endpoint is an HTTPS URL Tekmerion delivers notifications to. A merchant may register zero or more; each has its own identity and its own signing secret.

Register an endpoint

Provide the destination URL and whether it should start enabled. On success you receive an endpoint identity. The URL is immutable — to change where notifications go, register a new endpoint and disable the old one. There is no in-place URL edit.

Enable and disable

Enabling and disabling are explicit actions on an existing endpoint. A disabled endpoint receives no new deliveries; enabling resumes them. Disabling never affects the URL or the endpoint's identity.

Per-endpoint signing secret

Generate a webhook signing secret for the endpoint. Every notification delivered to it is signed with that secret as X-Tekmerion-Signature: v1=<hex>, alongside X-Tekmerion-Timestamp. Your receiver MUST verify both headers before processing the payload — see Signature verification.

• At most one signing secret is active per endpoint at a time.
• Rotating the secret generates a new one and invalidates the previous one; there is no dual-active overlap window in v1.0. After rotation, every newly executed delivery — including retries — is signed with the new secret. Verify against the secret currently active for the endpoint.
• These notification secrets are scoped per endpoint and are not shared with the KYT request surface, whose headers use the X-Tekmerion-KYT- prefix.

Merchant API key

The merchant API key authenticates your requests to the API and is scoped to one merchant_id.

• At most one API key is active per merchant at a time. Generating a new key invalidates the previous one.
• Revoke a key explicitly when it is no longer needed or may be compromised; a revoked key is retained for audit but no longer authenticates.
• The key value is shown once at issuance — store it securely. See Authentication.

The minimal go-live set

Before the first live payment you need:

• at least one enabled notification endpoint with an active signing secret, and a receiver that verifies signatures;
• one active merchant API key.

Confirm the full set of preconditions in the Go-live checklist.