Webhooks Customer Integration

This documentation describes how to use Webhooks for getting notifications on important events.

Introduction to webhooks

Webhooks is a user-defined HTTP callback that allow you to build or set up integrations which subscribe to certain events on agreements. When one of those events is triggered, we'll send a HTTP POST payload to the webhooks configured URL. Webhooks can be used to update agreement state, trigger notifications or notifying other dependent applications.

The webhook will never contain any sensitive information by design.

Usage

When you integrate with Egreement API you might want to inform your application when the state of any of your agreements has changed. Integrating webhooks in your application informs you about the state change along with the following benefits:

  • You do not need to poll Egreement API to be able to get the current status of any agreement.
  • It provides you with real time update of the pre-defined events and help you to minimize delays in your system.
  • It helps you to save resources (Network & System resources) by letting you avoid unnecessary polling.

Type of webhook integration

Company level

When webhooks is configured on your Company’s account on www.Egreement.com the webhook will be triggered for all agreements created. With a company level webhook configured there is no need to configure it for each agreement created.

Agreement level

You can configure a webhook for each agreement using the API Create request.

If you configure an Agreement level webhook it will have precedence over Company level webhooks.

Configuring webhooks

Company level webhooks

To configure company level webhooks, please contact Egreement support. The support team will configure a valid HTTP/HTTPS URL provided by you for your company account.

Agreement level

Agreement level webhooks are configured at each request to create an agreement by the Egreement API.

See API documentation.

Please note that there will be only one service URL for all events configured.

  •                                         "webhook": {    "events" : ["SIGNED_BY_ALL", "REJECTED"],    "url" : "https://www.egreement.com/notify"}
                                        

Events

When configuring a webhook, you can choose for which events you would like to receive notifications. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server.

Each event corresponds to a certain set of actions that can happen to your agreement. For example, if you subscribe to the SIGNED event you'll receive payload every time agreement is signed.

Events Description

POSTED

When the agreement is created

SIGNED

When someone signs the agreement

SIGNED_BY_ALL

When the agreement has been signed by all parties

REJECTED

When someone rejects signing the agreement

Payload

The webhook payload includes the agreement reference number and the event that has been triggered along with a timestamp.

See API documentation.

Please note that there will be only one service URL for all events configured.

  •                                         {  "referenceNumber" : "161000250228",  "event" : "SIGNED_BY_ALL",  "timestamp" : "156128461000"}
                                        

Design specification for service URL

There are some specifications on webhooks to meet when implementing a service to be used as webhooks service URL.

  1. Method : HTTP POST
  2. Accepts : JSON
  3. Response (within 30sec) :
    1. Success : HTTP 200
    2. Failure : Other than (HTTP 200)

Availability

In cases where the webhook service URL is not responding as expected:

  1. The request will be retried for 5 hours.
  2. After 5 hour a notification email will be sent to the company's designated contact alerting that the service is not available.
  3. The request will be retried for 24 hours (including 5 hours mentioned in point 1). After 24 hours the request will not longer be retried and the webhook is disabled. Another notification mail will be sent.
  4. In case service is down for 14 days all the events are flushed and can’t be reconciled.
  5. Once a webhook is disabled on your account, none of the new events will be preserved for notification.

Once the webhook has been disabled it will have to be enabled again by contacting the Egreement support team.

Limitations

There are a few important points which you need to handle when integrating webhook in your system.

  1. The order of events is not guaranteed at all time.
  2. It is possible that the same message can be delivered multiple times.

Once the webhook has been disabled it will have to be enabled again by contacting the Egreement support team.

Return to Top