Webhooks

Receive real-time notifications when events occur in your Propper account.

Setting Up Webhooks

1. Go to Settings → Webhooks in your dashboard
2. Click Add Endpoint
3. Enter your endpoint URL
4. Select the events you want to receive
5. Save and copy your signing secret

Webhook Payload

{
  "id": "evt_abc123",
  "type": "document.signed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "documentId": "doc_xyz789",
    "signerId": "sgn_def456"
  }
}

Verifying Signatures

All webhooks include a signature header for verification:

X-Propper-Signature: sha256=abc123...

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(`sha256=${expected}`));
}

Event Types

Sign Events

Event	Description
document.created	Document was created
document.sent	Document was sent for signing
document.viewed	Document was viewed by a signer
document.signed	Document was signed
document.completed	All signers have signed
document.declined	Signer declined to sign

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failed attempts, the endpoint is disabled and you'll be notified.