SnowSign Webhook Guide
Contents
Overview
SnowSign sends HTTP POST requests to your registered URL when contract events occur.
| Property | Value |
|---|---|
| Timeout | 5 seconds |
| Success | HTTP 2xx |
| Signature | HMAC-SHA256 |
| Failure handling | Automatic 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
- Open Organization settings → Webhooks → Add webhook.
- Enter a name, receiver URL, and at least one supported event.
- Save the secret securely; it is shown only when created.
- Use Test to verify delivery. If the secret is lost or exposed, regenerate it and update your receiver.
The test payload is:
{
"id": "webhook-event-uuid",
"event": "test",
"timestamp": "2025-01-06T10:00:00",
"data": { "message": "This is a test webhook event" }
}Events and payloads
Envelope
{
"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.
| Header | Value |
|---|---|
Content-Type | application/json |
X-Webhook-Event | Event type |
X-Webhook-Signature | HMAC-SHA256 hex signature |
Supported events
The following table lists event-specific fields in data, in addition to the common contract fields.
| Event | When emitted | Additional data |
|---|---|---|
contract.sent | Contract sent to participants or signing links activated | sent_at, expires_at, participants[] |
contract.viewed | A participant first views the contract | participant, viewed_at |
participant.signed | A participant signs | participant, signed_at, all_signed, signed_count, total_count |
participant.declined | A participant declines | participant, reason, declined_at |
contract.completed | All participants have signed | completed_at, participants[] including signed_at, download_url |
contract.cancelled | Sender cancels, or moves a contract awaiting signature to the trash | cancelled_at, reason |
contract.expired | Deadline passes | expired_at |
participant.revision_requested | A participant asks for changes instead of signing; signing pauses | participant, body (request text or null), requested_at |
contract.revised | The sender sends a revised version; signing restarts on the same links | revision_number, summary (change summary or null), expires_at, revised_at, notified_participants[] |
contract.signing_resumed | The sender resumes signing without changes | reply (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
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:
{ "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
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
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
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 appJavaScript / Express
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
| Symptom | Check |
|---|---|
| No delivery | HTTPS URL, firewall, delivery logs, and the Test action |
| Signature mismatch | Correct secret; raw bytes before parsing; regenerate a lost secret |
| Duplicate event | Deduplicate using the envelope's id, not contract ID |
| Timeouts | Acknowledge within 5 seconds; move business processing to a worker |
Document version: 1.8 (2026-09-04).