Setup Webhooks

Receive real-time notifications when events occur in Solifyn. Automate workflows and keep your systems synchronized with instant event delivery.

Webhooks provide real-time asynchronous notifications when specific financial or deployment events occur in your Solifyn account. Use webhooks to automate downstream workflows, update multi-tenant databases, send specialized fulfillment triggers, and keep your infrastructure completely synchronized.

Our webhook architecture adheres strictly to the Standard Webhooks specification, ensuring out-of-the-box compatibility with industry best practices and standard cryptographic verification patterns.

Key Features

• Real-time Delivery: Receive instant payload transmissions the millisecond a platform lifecycle change or checkout completes.
• Secure by Default: Every request is accompanied by cryptographically signed headers utilizing secure HMAC SHA256 configurations.
• Automatic Retries: Built-in fault tolerance featuring a robust 8-attempt retry sequence driven by an exponential backoff matrix.
• Granular Event Filtering: Avoid unnecessary processing loops and server traffic by subscribing only to the micro-events your backend handles.

---

Getting Started

Develop Safely Using Test Mode

Leverage our sandbox testing interface during development to process mock checkouts, active subscriptions, intentional cancellations, and refunds to trigger automated webhook schema events without moving live capital.

Step-by-Step Endpoint Registration

1. Access Webhook Settings: Log into your Solifyn Dashboard and navigate to Developer > Webhooks.
2. Create Webhook Endpoint: Click on the Add Webhook button to instantiate a new delivery configuration.

3. Specify Target URL: Input the secure HTTPS endpoint where your application server listens for incoming post requests.
4. Select Subscribed Events: Check the specific operational flags (e.g., payment.succeeded, subscription.active, dispute.challenged) your handler relies on. Leaving parent categories selected automatically registers your route for all associated sub-events.
5. Retrieve Secret Key: Copy your unique webhook Secret Key (whsec_...) from the endpoint details panel. This secret is vital for computing the signature verification step on your server.

Keep your webhook secret key entirely confidential. Never expose this value within client-side codebases, client-facing environment bundles, or public version control repositories.

Secret Rotation

If you suspect an active endpoint signature key has been compromised, you can initiate a zero-downtime transition via the dashboard by selecting Rotate Secret.

The rotation process generates a brand-new secret key immediately. To protect live data routing, the legacy secret remains active as a valid verification token for a strict 24-hour grace period before expiring permanently.

---

Webhook Delivery Specifications

Connection Timeouts

Solifyn maintains a strict 15-second connection and read timeout window for all dispatched webhooks. If your endpoint server fails to acknowledge the event request within this limit, the transmission is logged as a timeout failure and enters the retry cycle.

Process Webhooks Asynchronously!

To avoid hitting network timeout locks, your handler should validate the incoming payload signature, acknowledge receipt immediately by returning a clean 200 OK HTTP status code, and pass the actual transaction data block to a background task queue (e.g., Celery, BullMQ, or Amazon SQS) for processing.

Automatic Retry Matrix

If an endpoint times out, drops connections, or throws standard server errors (non-2xx status codes), our Svix infrastructure automatically schedules delivery retries using an exponential backoff progression:

Attempt Index	Backoff Delay Time	Operational Strategy Description
1	Immediately	First retry fires instantly following the initial failure event.
2	5 Seconds	Second attempt executed after a short stabilization window.
3	5 Minutes	Third delivery try with an escalated interval footprint.
4	30 Minutes	Fourth dispatch continuing the backoff progression pattern.
5	2 Hours	Fifth operational delivery retry with extended spacing layout.
6	5 Hours	Sixth verification attempt maximizing backoff boundaries.
7	10 Hours	Seventh technical attempt targeting structural path recovery.
8	10 Hours	Final Attempt: System marks the specific event message as Failed.

An individual event is retried a maximum of 8 times. You can utilize the Solifyn developer console to manually re-send single failed events or bulk-recover entire broken intervals at any time.

Idempotency & Message Ordering

Due to potential network routing retries or multi-region delivery variations, your handler may receive identical event payloads multiple times or out of absolute chronological order.

• Idempotency: Every webhook request injects a unique, immutable string within the webhook-id header. Always implement an idempotency ledger (e.g., matching IDs within a Redis cache layer) to drop duplicate requests safely.
• Payload State: Solifyn guarantees that every retry transmission contains the latest database payload snapshot available at the exact millisecond of delivery, regardless of when the initial trigger event originally fired.

---

Securing Webhooks & Verifying Signatures

To guarantee that incoming data blocks originate exclusively from Solifyn and have not been manipulated mid-transit, you must validate signatures cryptographically. Every webhook request bundles three distinct validation headers:

• webhook-id: The unique event identifier.
• webhook-timestamp: The Unix timestamp (seconds) tracking when the transmission initialized.
• webhook-signature: The computed HMAC SHA256 signature token.

Manual Cryptographic Verification

Because Solifyn leverages the open Standard Webhooks spec, we recommend using the official, lightweight, open-source verification libraries provided by the Standard Webhooks ecosystem rather than writing custom parsing blocks from scratch.

You can import their standard verification modules directly across multiple backends using their open libraries: Standard Webhooks Open Repositories.

Step-by-Step Manual Computation Routine:

1. Construct the signed text signature by concatenating the raw string value of the webhook-id, a literal period (.), the string value of the webhook-timestamp, another literal period (.), and the exact raw unparsed string body payload.
2. Compute an HMAC SHA256 hash of that concatenated string using your endpoint’s dashboard secret key (whsec_...) as the cryptographic key.
3. Perform a constant-time string comparison between your calculated output and the string array provided inside the webhook-signature header.

---

Implementation Example: Express.js Backend

Below is a complete, production-ready implementation inside an Express.js server utilizing the native standardwebhooks NPM package to securely handle payload signature parsing and asynchronous orchestration:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();

// Ensure the raw text/JSON body is preserved precisely for signature evaluation
app.use(express.json({ type: 'application/json' }));

const SEED_SECRET = process.env.SOLIFYN_WEBHOOK_SECRET; // Your whsec_... key
const webhookVerifier = new Webhook(SEED_SECRET);

app.post('/webhook/solifyn-payments', async (req, res) => {
  try {
    // Extract standard webhook compliance headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify signature integrity using the raw stringified request body
    const rawPayload = JSON.stringify(req.body);
    await webhookVerifier.verify(rawPayload, webhookHeaders);

    // 1. Acknowledge receipt immediately to avoid network timeouts
    res.status(200).json({ received: true });

    // 2. Offload the business logic to process asynchronously in the background
    processWebhookAsync(req.body).catch(console.error);

  } catch (error) {
    console.error('Crypto Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature matching array' });
  }
});

async function processWebhookAsync(payload: any) {
  // Route execution trees safely based on structural event types
  switch (payload.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(payload.data);
      break;
    case 'subscription.active':
      await handleSubscriptionActive(payload.data);
      break;
    default:
      console.log(`Unhandled platform event type: ${payload.type}`);
  }
}