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.
signature header.
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
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
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.
- A subscribed event occurs in your channel.
- Solidgate sends an HTTP POST request to your webhook endpoint. The request includes:
- Event details in the body
merchantheader with your webhook public keysignatureheader with the HMAC-SHA512 hashsolidgate-event-id,solidgate-event-created-at, andsolidgate-event-typeheaders
- Your server verifies the signature and processes the event.
- Your server responds with a 2xx HTTP status code within 30 seconds.
- If no valid response is received, Solidgate retries on the fixed schedule (up to 8 retries over 24 hours).
- A subscribed event occurs.
- Solidgate sends an HTTP POST request to your webhook endpoint. The request includes:
- Event details in the body
signatureheader with the HMAC-SHA256 hash
- Your server verifies the signature using the endpoint secret and processes the event.
- Your server responds with a 2xx HTTP status code.
- 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.
- Go to Developers > Channels.
- Select the channel you need.
- On the Channel details page, go to the Webhooks section.
- Click on Add endpoint.
- Select the events you want to subscribe to and enter the destination URL.
- Click Add to confirm.
- Go to Developers, and switch the API version to API v2.
- Select Webhook endpoints.
- Click on Create webhook endpoint.
- Enter a name and, optionally, a description.
- Enter the destination URL, select the events to subscribe to, and, optionally, select channels to scope delivery.
- Click on Create to confirm.
Event handling
Implement idempotent processing so duplicate deliveries do not cause unintended effects.
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 |
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.
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 |
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.