Webhooks notify your systems about payment, subscription, and billing events. Use them to automate order handling, update customer records, and trigger downstream workflows without repeatedly querying the API.

Solidgate offers webhooks v1 and v2 to match its two API versions.

Solidgate API v1 webhooks validate with the webhook public and secret keys, using the same HMAC-SHA512 model. Solidgate API v2 webhooks validate with the endpoint secret, using HMAC-SHA256 in the signature header. Webhooks v1 HMAC-SHA512

Endpoints are identified by a URL and a channel. Events are grouped by domain: card payments, alternative payments, subscriptions, and taxes. Validate deliveries with the webhook public and secret keys.

Includes

Card and alternative payment events Billing 1.0 events Tax events HMAC-SHA512 signature Retry schedule and idempotency headers Webhooks v2 HMAC-SHA256

Endpoints are created and managed through the API v2 endpoint management API. New endpoints start inactive until you activate them. Validate deliveries with the endpoint secret, and rotate it without downtime.

Includes

Billing 2.0 events Fraud and routing events Endpoint management API Channel scoping HMAC-SHA256 signature Secret rotation with grace period

Overview

Full request and response contracts remain in the Solidgate API reference.

Webhooks v1 Webhooks v2
Signature HMAC-SHA512 using webhook public and secret keys (wh_pk_ / wh_sk_), sent in the merchant and signature headers. HMAC-SHA256 using the endpoint secret, sent in the signature header. See Access to API and the Solidgate API v2 guide for signature generation.
Endpoint management API POST, GET, PATCH, and DELETE on /webhooks/endpoints. POST-only actions: /webhooks/create, /list, /get, /patch, /delete, and /rotate-key.
Endpoint identification A URL paired with a channel_id. An endpoint ID with included_channel_ids or excluded_channel_ids scoping. New endpoints start inactive until activated.
Event catalog Webhooks v1 grouped by domain: card payments, alternative payments, subscriptions and taxes of the Billing 1.0. Webhooks v2 across domains, including invoices, subscriptions, customers, payment instruments, fraud alerts, prevention alerts, and routing. Returns EVENT_TYPES_NOT_FOUND if a requested type is not supported.
Delivery retries and idempotency Deliveries retry on a fixed schedule from 15 minutes up to 24 hours. Deduplicate with the solidgate-event-id, solidgate-event-created-at, and solidgate-event-type headers. Deduplicate with the event_id, event_type, and occurred_at fields. Those fields appear inside the JSON payload only, so you must parse the body to route/dedupe.
Secret rotation Get new webhook public and secret keys from the Hub and generate the new signature. Call /rotate-key to receive a new secret. The previous secret stays valid during a grace period.

How it works

When an event occurs, Solidgate sends an HTTP POST request to your endpoint. The request includes event details in the body and a signature in the headers for verification.

Webhooks v1
  1. A subscribed event occurs in your channel.
  2. Solidgate sends an HTTP POST request to your webhook endpoint. The request includes:
    • Event details in the body
    • merchant header with your webhook public key
    • signature header with the HMAC-SHA512 hash
    • solidgate-event-id, solidgate-event-created-at, and solidgate-event-type headers
  3. Your server verifies the signature and processes the event.
  4. Your server responds with a 2xx HTTP status code within 30 seconds.
  5. If no valid response is received, Solidgate retries on the fixed schedule (up to 8 retries over 24 hours).
Webhooks v2
  1. A subscribed event occurs.
  2. Solidgate sends an HTTP POST request to your webhook endpoint. The request includes:
    • Event details in the body
    • signature header with the HMAC-SHA256 hash
  3. Your server verifies the signature using the endpoint secret and processes the event.
  4. Your server responds with a 2xx HTTP status code.
  5. If no valid response is received, Solidgate retries the delivery.

Manage webhooks

Create, update, and rotate webhook endpoints through the Solidgate API.

Webhooks v1

Create, list, patch, and delete endpoints through the API v1 endpoint management.

Webhooks v2

Create, list, update, and delete endpoints through the API v2 endpoint management.


Create, update, and rotate webhook endpoints through the Solidgate Hub.

Webhooks v1 To configure webhooks

  1. Go to Developers > Channels.
  2. Select the channel you need.
  3. On the Channel details page, go to the Webhooks section.
  4. Click on Add endpoint.
  5. Select the events you want to subscribe to and enter the destination URL.
  6. Click Add to confirm.
The endpoint is created in the active status. You can edit, deactivate, or delete it from the same page. Webhooks v2 To configure webhooks

  1. Go to Developers, and switch the API version to API v2.
  2. Select Webhook endpoints.
  3. Click on Create webhook endpoint.
  4. Enter a name and, optionally, a description.
  5. Enter the destination URL, select the events to subscribe to, and, optionally, select channels to scope delivery.
  6. Click on Create to confirm.
The endpoint is created in the INACTIVE status. You can activate or deactivate it, view the endpoint ID, channels, and secret key, or rotate the secret.

Event handling

Implement idempotent processing so duplicate deliveries do not cause unintended effects.

Webhooks v1 Webhooks v1 provides a solidgate-event-id header for deduplication and a solidgate-event-created-at timestamp for chronological ordering.

Header Description Example
solidgate-event-id Unique event ID for deduplication. e1765cf7-70f7-4e56-8fb2-bd88744a94d1
solidgate-event-created-at Event creation time in ISO 8601 Wiki format. 2025-06-05T12:34:56.789Z
solidgate-event-type The event type that occurred. card_gate.order.updated

Delivery order Webhook delivery order is not guaranteed. Use the solidgate-event-created-at timestamp to determine the actual sequence of events. Process events through a queue and store processed solidgate-event-id values for up to a week to catch duplicates. Webhooks v2 Webhooks v2 includes an event_id field and an occurred_at field in the event payload.

Field Description Example
event_id Unique event identifier. e1765cf7-70f7-4e56-8fb2-bd88744a94d1
occurred_at Event creation time in ISO 8601 Wiki format. 2025-06-05T12:34:56.789Z
event_type The event type that occurred. INVOICE_UPDATED

Delivery order Use the occurred_at field to sequence events if delivery order matters to your integration. Deduplicate incoming events using event_id according to your own retention policy.