While you can always check the status of a Workflow by polling the GET /workflows/{id} endpoint, this can be inefficient. For real-time notifications about important events happening in SignStack, Webhooks are the recommended approach.

Webhooks allow SignStack to proactively send a message (an HTTP POST request) to your application's endpoint whenever a specific event occurs, enabling faster and more efficient integrations.

What are Webhooks?

A webhook is essentially an automated notification sent from one system (SignStack) to another (your application) over the web. You subscribe to specific events you care about, and SignStack will push the relevant data to your registered URL as soon as those events happen.

Benefits of Using Webhooks

• Real-Time Updates: Get notified instantly when a workflow completes, a participant signs, or a step fails, without needing to constantly poll the API.

• Efficiency: Reduces the number of API calls your application needs to make, saving resources and potentially costs.

• Event-Driven Architecture: Enables you to build more responsive, event-driven integrations.

1. Setting Up a Webhook Endpoint

First, your application needs an HTTPS endpoint (URL) that can receive POST requests from SignStack.

Then, you register this endpoint with SignStack:

• API Endpoint: POST /v1/organizations/{organizationId}/webhook-endpoints

• Request Body:

  {
    "url": "[https://your-app.com/api/signstack-webhook](https://your-app.com/api/signstack-webhook)", // Your HTTPS endpoint
    "description": "Production CRM Notifications",
    "enabledEvents": [ // Specify which events you want to subscribe to
      "WORKFLOW_COMPLETED",
      "WORKFLOW_FAILED",
      "STEP_SIGNED"
      // Add other WorkflowEventType enums as needed
    ]
  }

  plaintext

• Response & Signing Secret: The API will respond with the created endpoint configuration, including a unique signingSecret. Save this secret immediately and securely! You'll need it to verify incoming requests. SignStack will not show it again.

2. Receiving Webhook Events

When a subscribed event occurs, SignStack will send a POST request to your registered url.

• Request Headers:

  • Content-Type: application/json

  • SignStack-Signature: Contains the HMAC signature for verifying the request authenticity (see below).

• Request Body (Payload):A JSON object containing details about the event:

  {
    "eventId": "evt_abc123xyz...", // Unique ID for this delivery attempt
    "eventType": "WORKFLOW_COMPLETED", // The type of event
    "eventTimestamp": "2025-10-26T02:05:12.345Z", // ISO 8601 timestamp
    "organizationId": "org_...",
    "data": { // Contextual data relevant to the event
      "workflowId": "wf_123abc456def",
      "status": "Completed",
      // ... Other relevant workflow/step/participant data
    }
  }

  plaintext

  (The exact structure of the data object will vary depending on the eventType.)

3. Verifying the Signature (CRITICAL SECURITY STEP ❗️)

Anyone could potentially send a fake request to your endpoint. You must verify the SignStack-Signature header to ensure the request genuinely came from SignStack.

1. Get the Secret: Retrieve the unique signingSecret associated with this webhook endpoint (the one you saved during setup).

2. Get the Payload: Use the raw POST request body you received.

3. Calculate Expected Signature: Compute an HMAC SHA-256 hash using the signingSecret as the key and the raw request body as the message.

4. Compare: Compare your calculated signature (usually hex-encoded) with the value provided in the SignStack-Signature header.

5. Reject if Mismatched: If the signatures do not match, ignore the request and return a 400 Bad Request or 403 Forbidden. Do not process it.

(SignStack will provide specific library examples in the documentation/SDKs for how to perform this verification easily in common languages.)

4. Processing the Event & Responding

If the signature is valid:

1. Process: Use the eventType and data payload to trigger the necessary logic in your application (e.g., update your database, notify users, etc.). Perform complex processing asynchronously in a background job if needed.

2. Respond Quickly: Send a 2xx HTTP status code (e.g., 200 OK or 202 Accepted) back to SignStack as quickly as possible (ideally within a few seconds) to acknowledge receipt. SignStack treats non-2xx responses or timeouts as delivery failures and may retry.

Retries

SignStack will automatically retry sending a webhook event if your endpoint returns a non-2xx status code or times out. Retries typically use an exponential backoff strategy for a limited number of attempts. Ensure your endpoint can handle potential duplicate event deliveries gracefully (e.g., by checking the eventId).

Webhooks provide a robust and efficient way to integrate SignStack events into your application's real-time processes.

➡️ Next: Guides: Connect with Zapier (Example) (Or the next relevant Integration guide)