3 posts tagged with "webhooks"

Until now, signers and approvers got the main document and its attachments, and it was up to them to read them.

API version 3.6.0 adds a guided signing flow: each signer and approver acknowledges the main document and each attachment, in order, before they can sign or approve.

Two flows​

Agreements now have a signing_flow field with two values:

• standard is how signing has always worked. Participants are presented with the documents, and reading them is their responsibility. It's the default, so existing integrations behave the same after upgrading.
• guided walks each signer and approver through the main document first, then each attachment in order. The sign or approve step stays locked until every document is acknowledged.

Turning it on​

Set signing_flow to guided when you create the agreement:

{
    "signing_flow": "guided"
}

You can also change it with PUT /agreements/{agreement_id} while the agreement is draft or open. The current value comes back on the agreement object.

Following along​

Each acknowledgement fires sign_event.document.acknowledged. Subscribe to it with a webhook to see how far each participant has come through the documents.

If you edit the agreement and send it again, earlier acknowledgements no longer count. Participants acknowledge each document again from the point it was resent, and the earlier acknowledgements stay in the history.

When it's worth it​

Guided signing fits agreements where the attachments matter as much as the main document, such as terms and conditions, policies, or appendices that people tend to scroll past. Keep standard for short agreements where an extra step per document would only slow people down.

Learn more about signing flows

Get started​

Upgrade your API client to version 3.6.0. You can do this from your API client settings on zigned.se by clicking "Upgrade".

Signing often takes days. Until now, the only PDF you could download was the one produced after everyone had finished.

API version 3.5.0 lets you generate a Partially Signed Document: the main document and its attachments, with the signatures and approvals collected so far.

What you get​

A Partially Signed Document is not the main document, and it is not an attachment. It is a generated PDF in the same composition as the final signed file, limited to the people who have already signed or approved.

Each successful generation is a revision. The one you should use is the revision with status current.

When you can generate one​

POST to agreements/{agreement_id}/documents/partially_signed_documents with an empty body once at least one signer or approver has acted. The response is queued, and file is null until generation finishes.

The request is rejected with an input validation error when nobody has acted yet, when a generation is already queued, or when the latest revision is still current.

Current, stale, and deprecated​

• current means this revision is up to date with the latest signatures and approvals.
• stale means it is a previous revision, generated before later signatures or approvals were collected.
• deprecated means the revision does not match the agreement as it stands now. That can happen because signatures were recalled, a document changed, or something else about the agreement no longer matches the PDF.

Notifications while it generates​

Subscribe to these events to get webhook notifications for partially signed documents: when generation starts, when it fails, and when the PDF is ready.

• agreement.partial_generation.started
• agreement.partial_generation.failed
• agreement.partial_generation.finalized

How it is billed​

Each successful generation is charged as a completed agreement of only the participants who had signed or approved at that moment. If you generate again after more people have acted, that file is a separate charge for the larger subset.

Queued generations, failed generations, and downloads are not charged. Fulfilling the agreement is still billed separately when everyone has finished.

Deleting a revision​

DELETE schedules removal, which completes within about 30 minutes. Cancel that schedule with the cancel-deletion endpoint before removal finishes.

Get started​

Upgrade your API client to version 3.5.0. You can do this from your API client settings on zigned.se by clicking "Upgrade".

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!