Guides
Status PageRoadmapTestimonies

Webhook messages

Suggest Edits

Yousign uses event-focused messages, this means the data contained within the message depends of the related event.

Headers

HeaderValue
Content-Typeapplication/json
X-Yousign-Signature-256The sha256 signature of the raw body, see Webhook Signature. (string)
X-Yousign-RetryThe number of retry operated, see Delivery Retry. (integer)
X-Yousign-Issued-AtThe moment when this specific webhook was sent. (timestamp)
User-AgentYousign Webhook Bot

Payload

All Webhooks we send have the same root schema:

{
  "event_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
  "event_name": "signature_request.done",
  "event_time": "1348177752",
  "subscription_id": "d09f0367-d80a-309c-a2ed-7083991fc564",
  "subscription_description": "A great webhook",
  "sandbox": false,
  "data": { ... }
}
AttributeValue
event_idA unique uuid.
event_nameName of Webhook's Event. (string)
event_timeThe moment when the underlying event occurred. It will stay constant even through retries. (string)
subscription_idId of the Webhook Subscription that triggered this specific Webhook. (uuid)
subscription_descriptionDescription of the Webhook Subscription that triggered this specific Webhook. (string)
sandboxIndicates if this Webhook was triggered in sandbox mode. (boolean)
dataRepresentation of the resource(s) concerned by Webhook Event.

📘

'Data' attribute content

The data attribute content depends of related Event, e.g.:

  • For Event of type Signature Request: it only contains a signature_request node,
  • For Event of type Signer: it contains a signature_request node and a signer node with additional data on the Signer whose action triggered this webhook,
  • For Event of type Electronic Seal: it only contains a electronic_seal node.
{
  "event_id": "b6c63685-c556-4a30-8fe9-b6f2b187d936",
  "event_name": "signature_request.activated",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "1c78c450-8b81-49f3-90d5-b0bb3caaba0e",
      "status": "approval",
      "name": "The name of your Signature Request",
      "delivery_mode": "email",
      "created_at": "2022-12-12T14:38:00+00:00",
      "timezone": "Europe/Paris",
      "email_custom_note": "Please sign these documents as soon as possible.",
      "expiration_date": "2023-06-12T21:59:00+00:00",
      "source": "public_api",
      "ordered_signers": true,
      "external_id": null,
      "workspace_id": "xxxxxxxx-f647-47d0-9a75-xxxxxxxxxxxx",
      "signers": [
        {
          "id": "7acd19ee-ac64-4634-a5f3-dc9f105ff8e9",
          "answers": [
            {
              "field_id": "89d519d7-63bd-45d2-8539-a10a9172368a",
              "field_type": "text",
              "question": "What is your name?",
              "answer": "John Doe"
            }
          ],
          "status": "notified"
        }
      ],
      "approvers": [
        {
          "id": "a4aae5b8-b152-45e3-9b88-1daa128dfb7b",
          "status": "notified"
        }
      ],
      "sender": null,
      "documents": [
        {
          "id": "55e5189b-a775-4685-8074-81356d0ff8b1",
          "nature": "signable_document"
        }
      ],
      "reminder_settings": null
    }
  }
}

{
  "event_id": "fe7dc059-5c18-4ddf-b772-1b8f1b57913b",
  "event_name": "signer.notified",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "1c78c450-8b81-49f3-90d5-b0bb3caaba0e",
      "status": "approval",
      "name": "The name of your Signature Request",
      "delivery_mode": "email",
      "created_at": "2022-12-12T14:38:00+00:00",
      "timezone": "Europe/Paris",
      "email_custom_note": "Please sign these documents as soon as possible.",
      "expiration_date": "2023-06-12T21:59:00+00:00",
      "source": "public_api",
      "ordered_signers": true,
      "external_id": null,
      "signers": [
        {
          "id": "7acd19ee-ac64-4634-a5f3-dc9f105ff8e9",
          "answers": [
            {
              "field_id": "89d519d7-63bd-45d2-8539-a10a9172368a",
              "field_type": "text",
              "question": "What is your name?",
              "answer": "John Doe"
            }
          ],
          "status": "notified"
        }
      ],
      "approvers": [
        {
          "id": "a4aae5b8-b152-45e3-9b88-1daa128dfb7b",
          "status": "notified"
        }
      ],
      "sender": null,
      "documents": [
        {
          "id": "55e5189b-a775-4685-8074-81356d0ff8b1",
          "nature": "signable_document"
        }
      ],
      "reminder_settings": null
    },
    "signer": {
      "id": "7acd19ee-ac64-4634-a5f3-dc9f105ff8e9",
      "info": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone_number": "+33760040000",
        "locale": "fr"
      },
      "answers": [
        {
          "field_id": "89d519d7-63bd-45d2-8539-a10a9172368a",
          "field_type": "text",
          "question": "Hello?",
          "answer": null
        }
      ],
      "status": "notified",
      "signature_level": "electronic_signature",
      "signature_authentication_mode": "sms"
    }
  }
}

{
  "event_id": "e134f047-bce0-4f2e-b3e1-342d1771470a",
  "event_name": "approver.notified",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "1c78c450-8b81-49f3-90d5-b0bb3caaba0e",
      "status": "approval",
      "name": "The name of your Signature Request",
      "delivery_mode": "email",
      "created_at": "2022-12-12T14:38:00+00:00",
      "timezone": "Europe/Paris",
      "email_custom_note": "Please sign these documents as soon as possible.",
      "expiration_date": "2023-06-12T21:59:00+00:00",
      "source": "public_api",
      "ordered_signers": true,
      "external_id": null,
      "signers": [
        {
          "id": "7acd19ee-ac64-4634-a5f3-dc9f105ff8e9",
          "answers": [
            {
              "field_id": "89d519d7-63bd-45d2-8539-a10a9172368a",
              "field_type": "text",
              "question": "What is your name?",
              "answer": "John Doe"
            }
          ],
          "status": "notified"
        }
      ],
      "approvers": [
        {
          "id": "a4aae5b8-b152-45e3-9b88-1daa128dfb7b",
          "status": "notified"
        }
      ],
      "sender": null,
      "documents": [
        {
          "id": "55e5189b-a775-4685-8074-81356d0ff8b1",
          "nature": "signable_document"
        }
      ],
      "reminder_settings": null
    },
    "approver": {
      "id": "a4aae5b8-b152-45e3-9b88-1daa128dfb7b",
      "info": {
        "first_name": "John",
        "last_name": "Approver",
        "email": "[email protected]",
        "phone_number": "+33760047222",
        "locale": "fr"
      }
    }
  }
}

{
  "event_id": "105d71ac-3633-4948-beec-43c0117a0e81",
  "event_name": "contact.created",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "contact": {
      "id": "3635896f-b5bd-4671-a02e-8e4c1f1cf077",
      "first_name": "John",
      "last_name": "Contact",
      "email": "[email protected]",
      "locale": "fr",
      "phone_number": "+33760047242",
      "company_name": "Acme",
      "job_title": "Doctor",
      "address_line_1": "string",
      "address_line_2": "string",
      "address_city": "string",
      "address_postal_code": "75009",
      "address_country": "France"
    }
  }
}

{
  "event_id": "105d71ac-3633-4948-beec-43c0117a0e81",
  "event_name": "user.completed",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "user": {
      "id": "3635896f-b5bd-4671-a02e-8e4c1f1cf077",
      "email": "[email protected]",
      "status": "completed",
      "locale": "en",
      "is_active": true,
      "role": "member"
    }
  }
}

{
  "event_id": "f8f5f331-0e45-455f-91be-eba052a71649",
  "event_name": "electronic_seal.done",
  "event_time": "1705921843",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "electronic_seal": {
      "id": "d4c48987-35c8-414c-b98f-7dc74f448052",
      "status": "done",
      "signature_level": "electronic_signature",
      "created_at": "2024-01-22T11:10:36+00:00",
      "external_id": null,
      "timestamp": false,
      "document_id": "6378e829-41bb-42d5-87dc-d5d2f2f24b4c",
      "image_id": "f91ba743-e61d-462a-8616-3d77e2d1bfc8"
    }
  }
}

{
  "event_id": "b6c63685-c556-4a30-8fe9-b6f2b187d936",
  "event_name": "signature_request.permanently_deleted",
  "event_time": "1670855889",
  "subscription_id": "ID_OF_WEBHOOK_SUBSCRIBTION",
  "subscription_description": "My Webhook description",
  "sandbox": false,
  "data": {
    "signature_request": {
      "id": "1c78c450-8b81-49f3-90d5-b0bb3caaba0e"
    }
  }
}

📘

Webhook and external_id

If you want to identify more precisely who is concerned by a webhook, you can link it to an external_id.

Updated 3 days ago