Skip to content

Suggested
API Dashboard
Sandbox Production

PaymentsHandling webhooks

Handling webhooks

How to register, verify, and process webhook deliveries from conomy_hq.

Webhooks are the platform’s primary mechanism to push state changes to your integration. Payment transaction updates are delivered as a signed POST to the URL you register for the environment.

For the catalog of events and payload shapes, see Webhooks API reference.

Register your endpoint

Section titled “Register your endpoint”

Configure a single webhook URL per environment through your dashboard. The platform will POST every event to that URL.

EnvironmentDashboard
Sandboxdashboard-sandbox.conomyhq.com
Productiondashboard.conomyhq.com

When you register the endpoint, also configure a secretKey. Conomy uses it to sign every delivery with HMAC-SHA256, so your handler can verify the request came from Conomy and not from a third party.

Verify the signature

Section titled “Verify the signature”

Every signed delivery includes a signature field in the JSON body. The signature is a 64-character hexadecimal HMAC-SHA256 digest of the JSON body without the signature field, computed with your secretKey.

Pseudocode:

received = body.signature
unsignedBody = { event: body.event, data: body.data }
expected = hmac_sha256(json(unsignedBody), secretKey).hex()
if not constant_time_equals(expected, received):
    return 401

Always compare in constant time. Always verify before trusting the transaction data.

Respond fast

Section titled “Respond fast”

The platform expects a 2xx response within 10 seconds. Your handler should:

  1. Verify the signature field.
  2. Enqueue the payload for asynchronous processing.
  3. Return 2xx.

Heavy work — database writes, external API calls, settlement reconciliation — belongs on a worker behind a queue, not inline in the webhook handler.

Be idempotent

Section titled “Be idempotent”

Webhook deliveries are at-least-once. The same (event, transaction.id, transaction.status) tuple may arrive twice — most often when your handler took too long on the first delivery and the platform retried.

Use that tuple as your idempotency key. Skip processing if you have already handled it.

key = event + ":" + transaction.id + ":" + transaction.status
if already_processed(key):
    return 200
mark_processing(key)
process(payload)
mark_processed(key)

Retry behaviour

Section titled “Retry behaviour”

When your endpoint returns a non-2xx response or times out, the platform retries with exponential backoff for up to 24 hours. After that, the event is dropped and surfaces in your delivery log.

Specifically:

  • First retry after 30 seconds.
  • Each subsequent retry doubles the delay, capped at 1 hour.
  • After 24 hours total, the delivery is marked as failed.

If you discover a backlog of failed deliveries, fix the root cause first, then request a replay from conomy_hq so you do not lose state.

Forward compatibility

Section titled “Forward compatibility”

Treat the webhook contract as additive:

  • New eventType values may appear at any time. Unknown event types should be logged and ignored, never errored.
  • New fields may appear on existing payloads. Unknown fields should be ignored, never errored.
  • The legacy transaction.status_changed event continues to fire for every status transition. New consumers should subscribe to the specific events for richer payloads, but existing handlers that only listen for the legacy event keep working.

Local testing

Section titled “Local testing”

In sandbox, you can simulate webhook deliveries by triggering the underlying lifecycle events through the API. For implementation code, use Validate webhook signatures.

Section titled “Related”