Receive events with webhooks

{
  "id": "evt_4e6a8c0b2d3f5a7c9e1b2d",
  "object": "event",
  "type": "envelope.completed",
  "created": 1791583201,
  "data": {
    "object": {
      "id": "env_3f9a1c7e2b8d4a6f9c0e1b",
      "object": "envelope",
      "status": "completed",
      "subject": "Order form, Northwind Traders",
      "metadata": {
        "crm_record": "006Qy00000AbCdE"
      },
      "completed_at": 1791583200,
      "documents": [
        {
          "id": "doc_1b4d7f0a3c6e9b2d5f8a1c",
          "signed_sha256": "4b8e2f6a0d3c7b1e5f9a2d6c0b4e8f3a7d1c5b9e2f6a0c4d8b3e7f1a5c9d2b6e",
          "…": "…"
        }
      ],
      "…": "…"
    }
  }
}

curl https://www.signsecure.org/v1/v1/webhook_endpoints \
  -H "Authorization: Bearer $SIGNSECURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourcompany.com/signsecure",
    "enabled_events": [
      "envelope.completed",
      "envelope.declined"
    ]
  }'

const res = await fetch('https://www.signsecure.org/v1/v1/webhook_endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIGNSECURE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://hooks.yourcompany.com/signsecure',
    enabled_events: [
      'envelope.completed',
      'envelope.declined'
    ]
  }),
});
const endpoint = await res.json();

import os
import requests

res = requests.post(
    "https://www.signsecure.org/v1/v1/webhook_endpoints",
    headers={"Authorization": f"Bearer {os.environ['SIGNSECURE_API_KEY']}"},
    json={
        "url": "https://hooks.yourcompany.com/signsecure",
        "enabled_events": [
            "envelope.completed",
            "envelope.declined"
        ]
    },
)
endpoint = res.json()

{
  "id": "we_8a0c2e4b6d1f3a5c7e9b0d",
  "object": "webhook_endpoint",
  "url": "https://hooks.yourcompany.com/signsecure",
  "enabled_events": [
    "envelope.completed",
    "envelope.declined"
  ],
  "status": "enabled",
  "secret": "whsec_Xq3vK8mN2pR5tW9yB4cF7hJ0lS6dG1aE3uZ8iO2nV5k"
}

import crypto from 'node:crypto';
import express from 'express';

const secret = process.env.SIGNSECURE_WEBHOOK_SECRET; // whsec_...
const app = express();

// The signature is over the raw bytes, so read the body raw.
app.post('/signsecure', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('SignSecure-Signature') || '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = Number(parts.t);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${req.body}`)
    .digest('hex');

  const valid = parts.v1
    && expected.length === parts.v1.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  const fresh = Math.abs(Date.now() / 1000 - timestamp) < 300;
  if (!valid || !fresh) return res.status(400).send('Bad signature');

  const event = JSON.parse(req.body);
  if (event.type === 'envelope.completed') {
    const envelope = event.data.object;
    // Find your record with envelope.metadata.crm_record, mark it signed,
    // and download the signed PDF. Do the slow work after responding.
  }
  res.sendStatus(200);
});

app.listen(3000);

import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

secret = os.environ["SIGNSECURE_WEBHOOK_SECRET"]  # whsec_...
app = Flask(__name__)


@app.post("/signsecure")
def signsecure():
    header = request.headers.get("SignSecure-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    payload = request.get_data()  # the raw bytes, exactly as sent

    expected = hmac.new(
        secret.encode(), f"{parts.get('t', '')}.".encode() + payload, hashlib.sha256
    ).hexdigest()
    valid = hmac.compare_digest(expected, parts.get("v1", ""))
    fresh = abs(time.time() - int(parts.get("t", 0))) < 300
    if not (valid and fresh):
        return "Bad signature", 400

    event = json.loads(payload)
    if event["type"] == "envelope.completed":
        envelope = event["data"]["object"]
        # Find your record with envelope["metadata"]["crm_record"] and update it.
    return "", 200

1791583201.{"id":"evt_4e6a8c0b2d3f5a7c9e1b2d","object":"event","type":"envelope.completed",…}