Create a subscription and trigger an event

To implement webhooks in your app through a webhook listener, you will need to create a webhook subscription. This configuration tells Yousign which events your app needs to be informed of, where to send information, if the message should be retried in case of failure, and some other settings.

Once you created your first subscription, you can trigger an event and use a tool like webhook.site to act as a webhook listener to see Webhook’s payload.

Create a subscription

The easiest way to create a webhook subscription is through the App. To get more details about each configuration available for the subscription, see Subscription.

1. Log in the App and navigate to the API > Webhooks section.
2. On the top right corner, click on Create a webhook.
3. Set your endpoint.
4. Set a description for your webhook subscription (optional).
5. Choose the Sandbox environment.
6. Choose the events you want to subscribe. For testing purpose, keep at least signature_request.activated, signature_request.done and signer.done.
7. Click on Create a webhook.

Trigger a test event

Now your subscription is created, you can trigger webhooks by triggering events listed in your subscription. To do that, create a new Signature Request in sandbox with the API, send it to yourself and sign it.

Webhooks will be sent to the endpoint you configured in your subscription. If you used webhook.site, you should see something like this:

Create your own webhook listener

A webhook listener is an application whose purpose is to expose an endpoint that will be called by Yousign to receive messages. The implementation of this webhook depends on your requirements but it must at least:

• handle webhooks payload in JSON format;
• return a 200 status response after handling the message. In case your application does not want to handle the message, it should still respond with a 200;
• return a response in less than 1s to get the best webhook experience or at least in less than 10s not to get considered in timeout. To get more information, see our Fail-fast policy;
  In order to respect a 1s response time, it's a best practice to download your files asynchronously, or after the response.
• be resilient of receiving the same message multiple times. It may happen that you receive the same message several times, in this case you should be able to know if you already processed it by checking the event_id, which is unique for each message, and therefore discard it if you want.

❗️

Timeouts

Be aware that if you send a 2XX or 3XX HTTP response after our timeout, it will also be considered as a failure and therefore can lead to trigger auto-retry. To avoid this issue, you should quickly acknowledge reception of the Webhook and operate any time-consuming processing asynchronously (using queuing systems like RabbitMQ, AWS SQS, or Azure Service Bus queues). To get more information, see Failure and Retry Policy.

📘

Use webhooks with ⚡ Zapier

Webhook subscriptions can be used directly via Zapier. Alternatively, we also have a Zapier integration directly available off the shelf.