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. Signature generation uses your API credentials and the Solidgate API v2 signing rules.
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 solidgate-event-id header. Use the solidgate-event-occurred-at header for ordering, and solidgate-event-type to identify the event without parsing the body.
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
    • solidgate-event-id, solidgate-event-occurred-at, and solidgate-event-type headers
  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. Under Webhooks, select 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.

Webhook logs

Webhook logs record every delivery attempt for a webhook endpoint. Use webhook logs to:

  • Debug failed or missing deliveries
    Filter by status to see the details or failure reason for each attempt, ad this is the first diagnostic step before other actions.
  • Verify a new endpoint
    After configuring an endpoint, check the logs to confirm the expected event types arrive, the payload matches your integration, and the endpoint returns a 2xx status code.
  • Confirm what was sent
    Use a notification ID or event ID from a support ticket to confirm what Solidgate sent, when, and the event details.

Each log entry shows the following details:

Section Description
Event The event ID, name, and time the event occurred.
Notification The notification ID, channel, destination URL, attempt number, time the notification was sent, and its body.
Response The status your endpoint returned, the response time, and the response body.
Webhooks v1 To view webhook logs

  1. Go to Developers, and switch the API version to API v1.
  2. Select Webhook log.
  3. Filter the list by Created at, Channel, Event, Status, Notification URL, Event ID, or Notification ID.
  4. Select a log entry to view the full event and response details.
Webhooks v2 To view webhook logs

  1. Go to Developers, and switch the API version to API v2.
  2. Under Webhooks, select Logs.
  3. Filter the list by Created at, Channel, Event, Status, Notification URL, Event ID, or Notification ID.
  4. Select a log entry to view the full event and response details.

Event retries run on a fixed schedule from 15 minutes up to 24 hours, for up to 8 attempts in total. The attempt number and status show where a notification is in that schedule.


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 provides a solidgate-event-id header for deduplication and a solidgate-event-occurred-at timestamp for chronological ordering.

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

Delivery order Webhook delivery order is not guaranteed. Use the solidgate-event-occurred-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.