Developer Centre

The MySign API · Enterprise plan

Webhooks.

Receive real-time notifications about envelope events. Configure webhook endpoints to react to signature requests, completions, and more.

Overview

Events find you.

MySign webhooks allow your application to receive real-time notifications when events happen with your envelopes. Instead of polling the API, you can configure a webhook URL that MySign will call whenever an event occurs.

Key features

  • Real-time event notifications
  • Secure webhook signature verification using HMAC-SHA256
  • Automatic retry logic with exponential backoff
  • Organisation-scoped webhooks
  • Comprehensive event payload data

Events

Webhook events.

MySign triggers webhooks for the following envelope lifecycle events:

envelope.created

Triggered when a new envelope is created via the API.

envelope.sent

Triggered when the envelope is sent to the signatory.

envelope.viewed

Triggered when the signatory opens the envelope.

envelope.signed

Triggered when the signatory completes their signature.

envelope.completed

Triggered when all signatures are collected and the envelope is finalised.

envelope.expired

Triggered when the envelope expires before being signed.

envelope.voided

Triggered when the envelope is manually voided/cancelled.

Payload

Webhook payload.

All webhook requests include a JSON payload with event details:

JSON
{
  "event": "envelope.completed",
  "timestamp": "2025-01-16T14:30:00Z",
  "data": {
    "envelope_id": "01JGXYZ123ABC456DEF789",
    "status": "completed",
    "template_id": "01JGABC456XYZ789DEF123",
    "signatory": {
      "name": "John Smith",
      "email": "[email protected]",
      "phone": "+44 7700 900123"
    },
    "created_at": "2025-01-16T10:00:00Z",
    "completed_at": "2025-01-16T14:30:00Z",
    "expires_at": "2025-01-23T10:00:00Z",
    "download_url": "https://api.mysign.co.uk/api/v1/native/envelopes/download/..."
  }
}

Payload fields

Field Type Description
event string The event type (e.g., envelope.completed)
timestamp string ISO 8601 timestamp when the event occurred
data object Event-specific data containing envelope details
data.envelope_id string (ULID) Unique identifier for the envelope
data.status string Current envelope status
data.download_url string URL to download completed document (only for completed status)

Security

Webhook signature verification.

MySign signs all webhook requests with HMAC-SHA256 to ensure authenticity. Always verify the signature before processing webhook data.

All webhook requests include an X-MySign-Signature header containing the HMAC-SHA256 signature of the request body.

Security warning

Always verify webhook signatures in production to prevent unauthorised requests. Unverified webhooks can be exploited by attackers.

Signature header
X-MySign-Signature: sha256=5d41402abc4b2a76b9719d911017c592

Verification example (PHP)

PHP
function verifyWebhookSignature($payload, $signature, $secret)
{
    // Extract the signature hash from the header
    $expectedSignature = str_replace('sha256=', '', $signature);

    // Compute the HMAC signature
    $computedSignature = hash_hmac('sha256', $payload, $secret);

    // Use hash_equals to prevent timing attacks
    return hash_equals($computedSignature, $expectedSignature);
}

// Usage in your webhook endpoint
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_MYSIGN_SIGNATURE'];
$webhookSecret = env('MYSIGN_WEBHOOK_SECRET');

if (!verifyWebhookSignature($payload, $signature, $webhookSecret)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature verified - process webhook
$event = json_decode($payload, true);

Verification example (JavaScript/Node.js)

Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Extract the signature hash from the header
  const expectedSignature = signature.replace('sha256=', '');

  // Compute the HMAC signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const computedSignature = hmac.digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(expectedSignature)
  );
}

// Usage in your Express webhook endpoint
app.post('/webhooks/mysign', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-mysign-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.MYSIGN_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Signature verified - process webhook
  const event = JSON.parse(payload);
  // Handle event...

  res.status(200).send('OK');
});

Configuration

Webhook configuration.

Configure your webhook URL in the MySign dashboard under Settings → Webhooks.

Requirements

  • HTTPS only: webhook URLs must use HTTPS (except localhost for testing)
  • Fast response: your endpoint should respond within 5 seconds
  • Success status: return HTTP 200–299 status code to acknowledge receipt
  • Idempotency: handle duplicate webhook deliveries gracefully

Best practices

  • Process webhooks asynchronously using a queue
  • Log all webhook requests for debugging
  • Use the envelope_id to prevent duplicate processing
  • Return 200 immediately and process in background

Reliability

Retry logic.

If your webhook endpoint is unavailable or returns an error, MySign will automatically retry delivery with exponential backoff.

After 5 failed attempts, the webhook will be marked as failed and no further retries will be attempted. You can view failed webhooks in your dashboard.

Retry schedule

1st retry  after 1 minute

2nd retry  after 5 minutes

3rd retry  after 15 minutes

4th retry  after 1 hour

5th retry  after 6 hours

■ then marked as failed · visible in dashboard

Development

Testing webhooks.

Use these tools to test your webhook integration during development:

Local testing

Use tools like ngrok or localtunnel to expose your local development server to the internet.

$ ngrok http 3000

Manual testing

Use the "Send Test Webhook" button in your dashboard settings to manually trigger a test webhook event to your endpoint.

Next: errors.

Every status code, error code and how to handle them.