SnowSignSnowSign
Back
Quick integration

SnowSign Webhook Guide

Contents

Overview

SnowSign sends HTTP POST requests to your registered URL when contract events occur.

PropertyValue
Timeout5 seconds
SuccessHTTP 2xx
SignatureHMAC-SHA256
Failure handlingAutomatic retry for transient failures; delivery logs and manual resend

Use HTTPS. Validate the signature before accepting an event, acknowledge promptly, and process work asynchronously. Deduplicate by event id: automatic and manual resends retain the same ID.

Setup

  1. Open Organization settings → Webhooks → Add webhook.
  2. Enter a name, receiver URL, and at least one supported event.
  3. Save the secret securely; it is shown only when created.
  4. Use Test to verify delivery. If the secret is lost or exposed, regenerate it and update your receiver.

The test payload is:

json
{
  "id": "webhook-event-uuid",
  "event": "test",
  "timestamp": "2025-01-06T10:00:00",
  "data": { "message": "This is a test webhook event" }
}

Events and payloads

Envelope

json
{
  "id": "webhook-event-uuid",
  "event": "contract.completed",
  "timestamp": "2025-01-06T15:00:00",
  "data": {
    "contract_id": "contract-uuid",
    "title": "Service Agreement",
    "dispatch_mode": "external",
    "responsible_permission_group": { "uuid": "group-uuid", "name": "All work" },
    "completed_at": "2025-01-06T15:00:00",
    "participants": [
      {
        "participant_id": "participant-uuid",
        "name": "Alex Kim",
        "email": "alex@example.com",
        "phone": null,
        "signing_order": 1,
        "security_method": "email",
        "signed_at": "2025-01-06T15:00:00"
      }
    ],
    "download_url": "https://..."
  }
}

timestamp and *_at fields are UTC. Contract event data includes contract_id, title, dispatch_mode, and responsible_permission_group: { uuid, name }. Titles, names, and participant-provided reasons retain their original language.

Participant records include participant_id, name, email, phone, signing_order, and security_method. Email may be null. Security methods are email, phone, password, or identity_verification; phone is the contact entered by the contract requester.

HeaderValue
Content-Typeapplication/json
X-Webhook-EventEvent type
X-Webhook-SignatureHMAC-SHA256 hex signature

Supported events

The following table lists event-specific fields in data, in addition to the common contract fields.

EventWhen emittedAdditional data
contract.sentContract sent to participants or signing links activatedsent_at, expires_at, participants[]
contract.viewedA participant first views the contractparticipant, viewed_at
participant.signedA participant signsparticipant, signed_at, all_signed, signed_count, total_count
participant.declinedA participant declinesparticipant, reason, declined_at
contract.completedAll participants have signedcompleted_at, participants[] including signed_at, download_url
contract.cancelledSender cancels, or moves a contract awaiting signature to the trashcancelled_at, reason
contract.expiredDeadline passesexpired_at
participant.revision_requestedA participant asks for changes instead of signing; signing pausesparticipant, body (request text or null), requested_at
contract.revisedThe sender sends a revised version; signing restarts on the same linksrevision_number, summary (change summary or null), expires_at, revised_at, notified_participants[]
contract.signing_resumedThe sender resumes signing without changesreply (or null), resumed_at, requesters[]

Select at least one of these ten events. Unsupported event names are rejected and duplicates are stored once. A useful baseline is contract.completed and contract.cancelled; add participant and viewing events as needed.

A contract cancelled by moving it to the trash has a null reason, and Public API lookups for it return 404 from then on.

When available, the completed PDF's download_url expires after one hour. It may be null if the final PDF is unavailable or a URL could not be generated. Obtain a fresh URL through the Public API if necessary.

Email delivery failures, bounces, and complaints are not customer webhook events. Use creator notification emails or the Public API contract list/detail/status endpoints.

Revisions

revision_number is the version participants see (the first send is 1). notified_participants are the participants SnowSign notified (empty if the sender chose not to, or for external delivery), and requesters are the participants who asked for changes; both use the participant shape. A revision clears participant-entered values, and participants sign again on the same links. With approval, contract.revised is emitted on final approval. SnowSign does not notify participants of externally delivered contracts; use these events to notify them.

Link signing emits participant.signed, followed by contract.completed. Since it has one signer, all_signed=true, signed_count=1, and total_count=1 in the signing event. Only these two events include the following reference in data:

json
{ "link_signing": { "id": "link-signing-uuid", "name": "Onboarding Consent" } }

Signing tokens and URLs are not included. Link creation, pause, resume, closure, and expiration do not have separate webhook events.

Signature verification

Compute HMAC-SHA256 using the webhook secret and the exact raw request-body bytes. Compare the resulting hex digest with X-Webhook-Signature using a timing-safe comparison. Do not parse and reserialize JSON before verification.

Python

python
import hashlib
import hmac

def verify_webhook(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode('utf-8'), payload_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

JavaScript

js
const crypto = require('crypto');

function verifyWebhook(payloadBody, signature, secret) {
  if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/.test(signature)) return false;
  const expected = crypto.createHmac('sha256', secret).update(payloadBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Receiver examples

These examples show signature verification and acknowledgment boundaries. Supply your own durable queue and idempotent worker. Persist/enqueue successfully before returning 2xx; an in-memory queue can lose accepted events on restart. A worker should apply each event ID once and retry failed processing.

Python / Flask

python
import hashlib
import hmac
import os
from flask import Flask, request, jsonify

app = Flask(__name__)
secret = os.environ['SNOWSIGN_WEBHOOK_SECRET']

def create_receiver(enqueue_event):
    @app.post('/webhook/snowsign')
    def receive():
        raw_body = request.get_data()
        expected = hmac.new(secret.encode('utf-8'), raw_body, hashlib.sha256).hexdigest()
        signature = request.headers.get('X-Webhook-Signature', '')
        if not hmac.compare_digest(expected, signature):
            return jsonify(error='Invalid signature'), 401
        event = request.get_json()
        enqueue_event(event)  # Your durable queue; failures must not return 2xx.
        return jsonify(received=True), 200
    return app

JavaScript / Express

js
const express = require('express');
const crypto = require('crypto');

function createReceiver(enqueueEvent) {
  const app = express();
  const secret = process.env.SNOWSIGN_WEBHOOK_SECRET;
  app.post('/webhook/snowsign', express.raw({ type: 'application/json' }), async (req, res, next) => {
    try {
      const signature = req.get('X-Webhook-Signature');
      if (!signature || !/^[a-f0-9]{64}$/.test(signature)) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
      const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
      if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
      let event;
      try { event = JSON.parse(req.body.toString('utf8')); }
      catch { return res.status(400).json({ error: 'Invalid JSON' }); }
      await enqueueEvent(event); // Your durable queue; deduplicate in the worker.
      return res.json({ received: true });
    } catch (error) {
      next(error);
    }
  });
  return app;
}

Troubleshooting

SymptomCheck
No deliveryHTTPS URL, firewall, delivery logs, and the Test action
Signature mismatchCorrect secret; raw bytes before parsing; regenerate a lost secret
Duplicate eventDeduplicate using the envelope's id, not contract ID
TimeoutsAcknowledge within 5 seconds; move business processing to a worker

Document version: 1.8 (2026-09-04).