§ Webhooks

Every state change, delivered.

Twelve event types. Signed with HMAC-SHA256. Delivered with exponential back-off and 30-day replay. Inspect every attempt — including the failures — in the developer console.

Event catalog.

All events fire from the same delivery queue, with the same headers and signing scheme.

envelope.sent

sent to all recipients

envelope.viewed

recipient opened the link

envelope.signed

a single signer completed

envelope.completed

all signers done · sealed

envelope.declined

signer rejected

envelope.expired

window closed unsigned

envelope.voided

sender voided manually

recipient.replaced

signer swapped mid-flight

template.created

new template available

team.member.added

seat used

key.rotated

API key rotated

compliance.flag

suspicious sign attempt

Payload example.

envelope.completed — the most common event. Subscribe and walk away; we’ll keep knocking until you ack.

POST → https://yourapp.com/hooks/vg-sign · envelope.completed⎘ Copy

// Headers
VG-Signature: t=1714230488,v1=4c2a9bd3…71ff
VG-Event-Id:  evt_8f4a2c1e9b3d
VG-Delivery:  attempt 1/8

// Body
{
  "id": "evt_8f4a2c1e9b3d",
  "type": "envelope.completed",
  "created": "2026-05-02T16:48:11Z",
  "data": {
    "envelope_id": "env_8f4a2c1e9b3d",
    "sealed_pdf_url": "https://api.vg-sign.com/v3/envelopes/env_8f4a/sealed.pdf",
    "sha256": "4c·a2·9b·d3·…·71·ff",
    "signed_by": [
      { "name": "Anna Volkov", "signed_at": "2026-04-27T14:33Z", "ip": "76.10.x.x" },
      { "name": "Mark Reston", "signed_at": "2026-04-28T11:02Z", "ip": "99.224.x.x" },
      { "name": "Julia Park",  "signed_at": "2026-05-02T16:46Z", "ip": "142.55.x.x" }
    ],
    "metadata": { "crmDealId": "deal_142" }
  }
}

Delivery guarantees.

HMAC-SHA256 signed

Each delivery includes a VG-Signature header. Verify before trusting the body.

Exponential back-off

8 attempts spread over 30 days. We retry only on 5xx, network errors, and timeouts.

30-day replay

Inspect any failed delivery in the developer console; replay with one click against your fixed endpoint.

Idempotent by event id

evt_ ids are stable across retries — store them and skip duplicates.