The MySign API · Enterprise plan
Receive real-time notifications about envelope events. Configure webhook endpoints to react to signature requests, completions, and more.
Overview
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.
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
All webhook requests include a JSON payload with event details:
{
"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
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.
X-MySign-Signature: sha256=5d41402abc4b2a76b9719d911017c592
Verification example (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)
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
Configure your webhook URL in the MySign dashboard under Settings → Webhooks.
Reliability
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.
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
Use these tools to test your webhook integration during development:
Use tools like ngrok or localtunnel to expose your local development server to the internet.
$ ngrok http 3000
Use the "Send Test Webhook" button in your dashboard settings to manually trigger a test webhook event to your endpoint.
Every status code, error code and how to handle them.