Help Center

Solidgate uses webhooks to handle asynchronous events for payments, subscriptions, and chargebacks. This ensures you receive all necessary information. A webhook uses your external application’s URL and sends HTTP requests when subscribed events occur. Solidgate sends POST requests to your merchant endpoint with event details in the request body.

Manage webhooks

Solidgate offers webhooks to notify your system about various events, ensuring communication and providing a way to build automated workflows.

At the core of webhook configuration is the endpoint. It defines how and where events are delivered and includes the following:

• Event types to receive
• Destination URL for delivery
• Identifier for event routing
• Descriptive name for configuration

Endpoints are identified by:

• url – the HTTP destination for webhook events
• channel_id – the delivery channel identifier

This combination ensures webhook events are sent to the correct destination using the right channel.

• Create webhook endpoints
• List the existing endpoints
• Update endpoint configurations
• Delete unused endpoints

1. A subscribed event occurs.
2. Solidgate sends an HTTP POST request to your webhook endpoint. The request includes event details and a unique signature for verification.
3. Solidgate expects your server to:
   • Process the webhook based on your business logic
   • Verify the event signature for security
   • Respond with a 2xx HTTP status code within 30 seconds
4. If no valid response is received in time, Solidgate retries the delivery.

1. Set up an endpoint on your server to receive webhook notifications from Solidgate.
2. Add the endpoint in the Solidgate Hub with the handler URL and your specified events.

1. Go to Developers > Channels.
2. Find the channel you need and click on it.
3. On the Channel details page, go to the Webhooks section.
4. Click on Add endpoint.
5. In the pop-up window, set up the endpoint:
   • Select the events you want to subscribe to.
   • Enter the URL for event delivery.
6. Click Add to confirm.

Card payments

• card_gate.order.updated
  Updated card order Webhook provides secure, real-time updates on card order status, enabling automated responses to changes.
• card_gate.chargeback.received
  Received dispute Webhook provides chargeback notifications, enabling automated updates upon receipt of a new dispute for a card order.
• card.network_token.created
  Created network token Webhook provides the creation of a network token by Visa Token Service, Mastercard Digital Enablement Service, or Secure Card on File.
• card.network_token.updated
  Updated network token Webhook provides updates on network tokens, enabling immediate system adjustments and reflecting changes in their status.
• card_gate.prevention_alert.received
  Received prevention alert Webhook provides card alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
• card_gate.fraud_alert.received
  Received fraud alert Webhook provides fraud alerts, denoting the acquisition of a TC40/SAFE alert to help merchants take swift preventive actions.

• Updated card order
  Provides secure, real-time updates on card order status, enabling automated responses to changes.
• Received card dispute
  Provides chargeback notifications, enabling automated updates upon receipt of a new dispute for a card order.
• Created card network token
  Provides the creation of a network token by Visa Token Service, Mastercard Digital Enablement Service, or Secure Card on File.
• Updated card network token
  Provides updates on network tokens, enabling immediate system adjustments and reflecting changes in their status.
• Received dispute prevention alert
  Provides card alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.
• Received card fraud alert
  Notifies merchants when TC40/SAFE fraud alerts are received from card networks to help them take swift preventive actions.

Alternative payments

• alt_gate.order.updated
  Updated alternative order Webhook provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
• alt_gate.paypal_dispute.received
  Received PayPal dispute Webhook provides updates on the creation and progression of PayPal disputes, offering critical insights into their lifecycle.
• card_gate.prevention_alert.received
  Received prevention alert Webhook provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.

• Updated alternative order
  Provides secure notifications for alternative payment methods, representing updates on the status of an alternative order.
• Received PayPal dispute
  Provides updates on the creation and progression of PayPal disputes, offering critical insights into their lifecycle.
• Received dispute prevention alert
  Provides APM alerts for chargeback risks, indicating the reception of an issuer network alert to enhance dispute resolution.

Subscription

• subscription.updated.v2
  Subscription updates Webhook provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.

• Subscription updates
  Provides subscription updates, including initiation and modification events, highlighting subscription or related order status changes.

Taxes

• taxer.tax.calculated
  Calculated tax Webhook provides notifications about tax calculations for transactions, delivering key details like calculated amounts and tax type breakdowns, ensuring merchants have accurate and accessible tax information.

• Calculated tax
  Provides notifications about tax calculations for transactions, delivering key details like calculated amounts and tax type breakdowns, ensuring merchants have accurate and accessible tax information.

Delivery attempts

If the webhook notification fails due to an incorrect response, the retry mechanism automatically makes several attempts to resend it.

Notification delivery attempts follow the structured schedule below:

1. 15 minutes after the first failed notification
2. 30 minutes after the first failed retry
3. 1 hour after the second failed retry
4. 2 hours after the third failed retry
5. 4 hours after the fourth failed retry
6. 8 hours after the fifth failed retry
7. 16 hours after the sixth failed retry
8. 24 hours after the seventh failed retry

Security

Webhook event security is handled similarly to API authentication. In each notification, you receive the merchant and signature values in the headers.

• merchant value corresponds to the webhook public key wh_pk_.
• signature value is calculated using the webhook public and secret keys, which helps verify the authenticity and integrity of the webhook data transmitted between Solidgate and the merchant’s server.
  The data variable within the generateSignature function refers to the payload sent via the webhook. This data can include event-related information, like order events, and is sent by Solidgate as part of the triggering HTTP request body.

Retrieve the merchant wh_pk_ from the request headers and verify if you possess the corresponding credentials.

Generate a signature from the received body using the generateSignature function, as you would when sending a request to a gateway.

When generating a signature, it is essential to use the raw JSON data exactly as it is received in the body of the API request. Avoid any modifications or processing through serializers, as these can alter the structure of the data, leading to signature mismatches.

• Double-check that the jsonString used for signature generation matches the body received in the API request without alterations.
• Ensure that data passed into the generateSignature function retains its original structure and format to preserve data integrity.

public function generateSignature($data)
{
  return base64_encode(
    hash_hmac('sha512', $wh_pk. $ data. $wh_pk, $wh_sk_)
  );
}

Event handling

Occasionally, you may receive duplicate events during notification retries or when resending requested events. To mitigate this, implement idempotent processing in your integration using the unique event ID provided in the request headers. This approach prevents negative effects from duplicate events without requiring additional verification of the request body content.

The event ID provides a reliable mechanism for preventing duplicates and managing events efficiently.

Handle non-ordered events

Solidgate webhooks enable asynchronous event communication for payments, subscriptions, and chargebacks. However, the order of received webhook events may not always match the sequence of their occurrence. Use the solidgate-event-created-at timestamp to determine the actual chronological order of events.

• Asynchronous event processing
  Implement a queue-based approach to process incoming events instead of handling them synchronously.
  
  This is crucial due to the timeout constraints on webhook sending. Synchronous processing that exceeds the timeout limit may lead to webhooks being marked as undelivered, which can complicate the order of event processing.
  
  Use the solidgate-event-created-at timestamp to maintain proper chronological processing regardless of delivery sequence.

• Event ordering
  Use the solidgate-event-created-at timestamp to sort events chronologically. This ensures you handle events in the correct order, regardless of when they were received.
• Accumulating webhooks
  Store the incoming webhook for about a minute to collect all relevant data. For TTL, store processed solidgate-event-id for up to a week to cover potential duplicates and ensure efficient handling of events.
• Handling event collisions
  When events cannot be processed due to insufficient data from delayed delivery, use the Solidgate API to retrieve the necessary information.

By following these best practices, you can manage non-ordered events in webhooks, which ensures accurate and reliable event processing in your system.