One post tagged with "events"

Building a great e-signing experience doesn’t stop at signing itself. Your system also needs to stay up to date as documents move through their lifecycle: created, sent, signed, cancelled. Polling for updates or relying on manual refreshes is slow and brittle.

In this short post, we’ll explore how Webhooks let you react to signing events instantly, so your workflows stay automatic and your users stay in the loop.

The Problem: Slow and Unreliable Polling​

Imagine you have an internal dashboard showing the status of agreements your customers sign. Without Webhooks, you have to periodically fetch the agreement status from our API:

1. Agreement created
   You store the agreement ID and show it as “Pending”.
2. Polling begins
   Every minute you call the API to check if the agreement has been signed.
3. Laggy updates
   The status might update minutes later, depending on when your polling job runs.
4. Unnecessary load
   You’re wasting resources asking the API about agreements that haven’t changed.

Webhooks solve all of this by sending you a real-time notification as soon as something happens.

Getting started with Webhooks​

Let’s walk through a minimal example of using Webhooks to update your system in real time when an agreement is signed:

1. Create your webhook endpoint
2. Register the webhook in Zigned
3. Verify incoming webhook events
4. Process the event and update your system

1. Create your webhook endpoint

You’ll need an HTTPS endpoint in your system that accepts POST requests with a JSON body. Here’s a minimal example using Express.js:

// Letss assume you have an Express.js app
const express = require('express')
const app = express()
app.use(express.json()) // Middleware to parse JSON bodies

app.post('/webhooks/zigned', (req, res) => {
    const event = req.body

    // Validate the event (more on this below)
    console.log('Received webhook event:', event)

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

2. Register the webhook

Use our API to register your webhook URL. You can choose which events you want to subscribe to.

curl -X POST https://api.zigned.se/rest/v3/webhooks \
 -H "Content-Type: application/json" \
 -d '{
  "url": "https://yourapp.com/webhooks/zigned",
  "events": ["agreement.lifecycle.finalized"]
 }'

3. Verify the webhook event

Each webhook request includes a signature header you can use to verify authenticity. This helps you confirm the event really came from Zigned. You’ll find instructions and your secret in the developer dashboard.

Example Node.js verification snippet:

const crypto = require('crypto')

function verifySignature(rawBody, signature, secret) {
    const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

4. Process the event

Once verified, you can safely update your system. For example, mark the agreement as signed in your database or trigger any follow-up workflows.

// Verify the webhook event. Assume your webhook secret is stored in an environment variable.
const data = verifySignature(req.body, req.headers['x-zigned-signature'], process.env.ZIGNED_WEBHOOK_SECRET)

switch(data.event) {
    case 'agreement.lifecycle.finalized': {
        // Update your agreement status in your system
        // Assume you have a function updateAgreement that takes an ID and status
        updateAgreement(data.data.agreement_id, 'signed')
        break
    }
    case 'agreement.lifecycle.cancelled': { ... }
    default: { ... }
}

And that’s it!​

With Webhooks, you get real-time visibility into agreement status without any polling or delays. Whether you’re updating dashboards, sending notifications, or triggering workflows, Webhooks make sure your system stays perfectly in sync.

If you haven’t already, head over to your developer dashboard and register a webhook to see it in action. Happy building!