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

Headers

Header	Value
Content-Type	`application/json`
X-Yousign-Signature-256	The `sha256` signature of the raw body, see Webhook Signature. (string)
X-Yousign-Retry	The number of retry operated, see Delivery Retry. (integer)
X-Yousign-Issued-At	The moment when this specific webhook was sent. (timestamp)
User-Agent	`Yousign 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": { ... }
}

Attribute	Value
event_id	A unique uuid.
event_name	Name of Webhook's Event. (string)
event_time	The moment when the underlying event occurred. It will stay constant even through retries. (string)
subscription_id	Id of the Webhook Subscription that triggered this specific Webhook. (uuid)
subscription_description	Description of the Webhook Subscription that triggered this specific Webhook. (string)
sandbox	Indicates if this Webhook was triggered in sandbox mode. (boolean)
data	Representation 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.

Webhook messages

Headers

Payload

📘
'Data' attribute content

📘
Webhook and `external_id`

Headers

Payload

📘'Data' attribute content

📘Webhook and external_id

📘
'Data' attribute content

📘
Webhook and `external_id`