API guide

Welcome to the Anvil API! This is the same API that powers Anvil, giving you the ability to access all of the features available in the Anvil UI.
API introduction
Getting started
Workflows
Etch E-sign
PDF filling
PDF generation
WebhooksHandling a webhookResponse & RetriesPer-Object Webhook URLsEtchPacket Webhook URLWeldData Webhook URLTest ActionswebhookTestWorkflow ActionsweldCreateweldCompleteE-Signature ActionssignerCompleteetchPacketComplete
Object shapes
GraphQL guide
Glossary
GraphQL reference
View engineering blog

Webhooks

Anvil can POST to an endpoint on your server with a webhook. Enable webhooks on your Organization Settings -> API Settings page. You do not need to set a static URL if you plan to only use per-object webhook URLs.

Webhook Settings

Handling a webhook

When an action happens on Anvil's side, Anvil will POST JSON to the URL you specify (either static or per-object). The payload will look like the following:

{
  action: 'actionName',
  token: '38Gp2vP47zdj2WbP1sWdkO2pA7ySmjBk',
  data: 'RIaPFMKCP1Lqf8djqhG0uiN3UvrqQ5HgLxTBnigvSoQGwUeeRu...',
}
  • action is the name of the action that happened.
  • token is generated when you enable webhooks on your Organization Settings page. It is a way for your server to make sure Anvil is making the request. Treat this as you would an API key. It is up to you to check that these match in your webhook handler.
  • data is the actual payload of the webhook. It is encrypted with your organization's RSA key if you choose to create a keypair. Create a keypair on your Organization Settings -> API Settings page. If no keypair exists, data will be sent as unencrypted JSON.
    • See our notes on encryption for information on creating a keypair and using it to decrypt data.

Response & Retries

Your server should respond to the POST with a 204 No Content or 200 OK status code. Anvil will ignore the response body.

If your server responds with a status code >= 400 or times out, Anvil will consider the call a failure and the request will be retried. It will attempt a total of 5 times.

The webhook will be retried in these rough intervals until it sees a successful code or gives up:

Immediately, 5 seconds, 1 min, 3 min, 7 min (i.e. the last call will happen about 11 min from initial call)

Per-Object Webhook URLs

There are two ways to specify webhook URLs.

  1. A static URL. When you enable webhooks, you can specify a URL. This URL will receive all webhook messages.
  2. Set a specific webhookURL when creating or updating an object in the system.

If you have both a static URL set and an object-specific URL set, the object-specific URL will override the static URL.

EtchPacket Webhook URL

// The webhookURL will receive all webhooks on related
// objects. e.g. etchPacketComplete and signerComplete on
// the packet's signers.
createEtchPacket({
  ...,
  webhookURL: 'https://specific.com/url',
  ...
})
updateEtchPacket({
  eid: '...',
  webhookURL: 'https://specific.com/url',
  ...
})

WeldData Webhook URL

// The webhookURL will receive all webhooks on related
// objects. e.g. weldComplete and signerComplete on the
// weldData's signers
forgeSubmit({
  weldDataEid: null,
  webhookURL: 'https://specific.com/url',
  ...
})
createWeldData({
  weldEid: '...',
  webhookURL: 'https://specific.com/url',
  ...
})
updateWeldData({
  eid: '...',
  webhookURL: 'https://specific.com/url',
  ...
})

Test Actions

webhookTest

Called when the test button is clicked from the webhook settings UI. This is only available for static webhook URLs.

Webhook Settings Test
{
  action: 'webhookTest',
  data: {...},
  token: '38Gp2vP47zdj2WbP1sWdkO2pA7ySmjBk'
}

Workflow Actions

weldCreate

Called when a workflow is created in the workflow builder.

{
  action: 'weldCreate',
  data: 'RIaPFMKCP1Lqf8djqhG0uiN3UvrqQ5HgLxTBnigvSoQGwUeeRu...',
  token: '38Gp2vP47zdj2WbP1sWdkO2pA7ySmjBk'
}

Once decrypted, it will have the following structure:

{
  eid: 'KtHa4IhKyoZO6hbQaQJK',
  name: 'New Office',
  slug: 'new-office',
  forges: [{
    eid: 'v9vlkzYU0e6IKpeYimIP',
    name: 'Virtual Office Setup'
    slug: 'new-office-admin'
  }, {
    eid: '0ZTRyrIlfcYsAo6A95Qk',
    name: 'Client Details',
    slug: 'new-office'
  }]
}

weldComplete

When an entire workflow is finished, it will call the webhook with the weldComplete action. It will only call this after all web forms in the workflow have been completed and all signers have signed their documents.

Note: the weldComplete webhook is called on test submissions. There will be an isTest field in the payload.

{
  action: 'weldComplete',
  data: 'RIaPFMKCP1Lqf8djqhG0uiN3UvrqQ5HgLxTBnigvSoQGwUeeRu...',
  token: '38Gp2vP47zdj2WbP1sWdkO2pA7ySmjBk'
}

Once decrypted, it will have the following structure:

{
  isComplete: true,
  isTest: false, // is this a test submission?
  eid: 'GHEJsCVWsR1vtCx3WtUI',
  documents: [{
    type: 'application/zip',
    url: 'https://app.useanvil.com/download/GHEJsCVWsR1vtCx3WtUI.zip',
  }],
  weld: {
    eid: 'KtHa4IhKyoZO6hbQaQJK',
    slug: 'new-office'
  },
  forges: {
    'new-office-admin': {
      eid: 'v9vlkzYU0e6IKpeYimIP',
      name: 'Virtual Office Setup'
    },
    'new-office': {
      eid: '0ZTRyrIlfcYsAo6A95Qk',
      name: 'Client Details'
    },
  },
  submissions: {
    'new-office-admin': {
      eid: 'sZXFCa4EF3cVRo0Qipqc',
      payload: {
        customerName: { value: 'SomeCo LLC', type: 'shortText' },
        // ...
      },
    },
    'new-office': {
      eid: 'xdwoukKDmOzLd5xbkApw',
      payload: {
        name: { value: 'Bobby Joe', type: 'shortText' },
        // ...
      },
    },
  },
}

E-Signature Actions

signerComplete

Called when a signer has finished signing their respective documents.

{
  action: 'signerComplete',
  data: 'RIaPFMKCP1Lqf8djqhG0uiN3UvrqQ5HgLxTBnigvSoQGwUeeRu...',
  token: '38Gp2vP47zdj2WbP1sWdkO2pA7ySmjBk'
}

Once decrypted, it will have the following structure:

{
  name: 'Sally Jones',
  email: 'sally@jones.net',
  status: 'completed',
  eid: '0ZTRyrIlfcYsAo6A95Qk',
  routingOrder: 1,


  // If this signer was part of a workflow, the weldData key will be present
  weldData: {
    eid: '47zdj2WbP1sWdkO2pA7y',
  },


  // If this signer was part of an etch signature packet, the etchPacket key will be present
  etchPacket: {
    eid: '47zdj2WbP1sWdkO2pA7y',
  },


  documentGroup: {
    eid: '8jJ9yrIlfcYsAo6A95Qk',
    status: 'partial',
  },
  signers: [{
    name: 'Sally Jones',
    email: 'sally@jones.net',
    status: 'completed',
    eid: '0ZTRyrIlfcYsAo6A95Qk',
    routingOrder: 1,
  }, {
    name: 'Roscoe Jones',
    email: 'roscoe@jones.net',
    status: 'sent',
    eid: 'F6h77rIlfcYsAo6A95Qk',
    routingOrder: 2,
  }],
}

etchPacketComplete

When an Etch signature packet is completed, the etchPacketComplete action will be called. This webhook action will only be called after all signers have signed.

Note: the etchPacketComplete webhook is called on test submissions. There will be an isTest field in the payload.

Once decrypted, it will be the structure:

{
  name: 'NDA Packet',
  eid: 'DEtCx3WtJsCIVWGsR1vU',
  isTest: true,
  status: 'completed',
  detailsURL: 'https://app.useanvil.com/org/my-org/etch/DEtCx3WtJsCIVWGsR1vU',
  downloadZipURL: 'https://app.useanvil.com/api/document-group/FhrKzFgrN5vZ4mwzy.zip',
  documentGroup: {
    eid: 'FhrKzFgrN5vZ4mwzy',
    status: 'completed',
  },
  signers: [
    {
      name: 'Sally Signer',
      email: 'sally@example.org',
      aliasId: 'Sally',
      eid: 'wAoklfcF67rI6A95Q7Yh',
      status: 'completed',
      routingOrder: 1,
    },
    // ...
  ],
  etchTemplate: {
    eid: 'fdwopwkKuxbkADmOzLx',
  },
}
back to articles