RSign webhooks

Webhooks allow web applications to communicate with each other. It allows sending real-time data from one application to another whenever a given event occurs.
Whenever a subscribed event occurs in RSign, the webhook sees the event, collects the data, and sends it to the URL specified in the form of an HTTP request.

Whenever an RSign customer is interested to know about any event in RSign like signing a document, or envelope status, they can set up a webhook. Whenever an event happens, the corresponding webhook will be triggered and information will be passed to the customer application in the desired manner.

Important: Webhooks can only be configured by users with customer administrator role in RSign. The Webhooks module is disabled by default. If you wish to enable the Webhooks module, please contact the RPost Support team.

.

This article covers the following topics:

• Configuring webhooks
• Editing webhooks
• Disabling webhooks
• Implementation of webhooks: customer application

Configuring webhooks

To configure webhooks events, follow these steps:
1. Access the Webhooks module, located in the Company settings tab.

2. To add a new event, click on the Add webhook button. You will be directed to the Add/edit webhook tab.

3. Complete the necessary fields:
- Event: Name of the event to be configured. Select from the available events dropdown.
- Secret key: Automatically generated UUID using UUID-4 generator included in API header. The UUID is appended by adding the prefix ‘RPWH’. It is a read-only field.
Sample secret key: RPWH-897776d5-13f1-4293-93dd-424ddd9cea7a
There are three icons next to the Secret key field:
• View/Hide – to view or hide a secret key
• Refresh – to refresh the secret key and generate a new one.
• Copy – to copy the secret key

4. After selecting the event type from the drop-down, the corresponding parameter field is visible. Select the required parameters. Parameters are internally mapped with events.

5. Once all the required fields are complete accordingly, click on Save. The newly added event details will be visible in the webhooks tab.

Note: RSign does not allow the selection of the same event multiple times. Once an event is configured, it is not available for selection again. In the above example, if the event Document Signed is configured, then the same is not available for selection again.

<back to article content

Editing webhooks

To edit a configured webhook, follow these steps:
1. Click on the View/Edit button available in the actions column on the webhooks tab. The corresponding webhook will be opened in the Add/Edit Webhook tab.
Note: When the webhook is opened for editing, the event drop-down is not editable, as it is only displayed for informational purposes.

2. Make the necessary changes and click on Save.

<back to article content

Disabling webhooks

To disable an active webhook, follow these steps:
1. Click on the View/Edit button available in the actions column on the webhooks tab. The corresponding webhook will be opened in the Add/Edit Webhook tab.
2. Select the Inactive option from the Status dropdown and save your changes.

Disabled webhooks are not triggered when the corresponding event happens.

<back to article content

Implementation of webhooks: customer application

This section explains how to implement webhooks on the customer application side. When any configured event occurs in the RSign application, the webhook triggers the customer API with configured parameters and the Secret key as part of API headers.

Webhook events

Webhook event parameters

Implementation of the Envelope Status event

The Envelope Status event should be configured in the RSign Webhook settings as shown in the screenshot below:

When an envelope status is changed, the API gets triggered with the following parameters in JSON format based on the configuration:

Sample JSON payload data from the Webhook to the callback URL:
POST HTTPS 1.2
Host: Customer configured endpoint
RPWHSecretKey: RPWH238023JSDVB23923
Content-Type: application/JSON
Accept: application/JSON
Accept-Charset: utf-8
{
   "EnvelopeId": "67d32b5e-ef28-4560-9c7a-8ba14838197e",
   "EnvelopeCode": "29602465-1772-DFEB-3729-EFFC",
   "SenderEmail": "rsigncustadm@yahoo.com",
   "EnvelopeStatus": "Completed",
   "EnvelopeStatusOld": "Waiting for Signature",
   "Timestamp": "2021-11-24 15:56:55.577",
   "SignerEmail": "name@domain.com",
   "SignerStatus": "Signed",
   "ReferenceCode": 12345,
   "ReferenceEmail": "name@domain.com"
}

Secret Key in the API header:
The secret key configured in the RSign application for any webhook event will be sent as part of API headers.

Implementation of the Envelope Completed event

When any envelope is completed, the API gets triggered with the following parameters in JSON format based on the configuration:

Sample JSON payload data from the Webhook to the callback URL:

POST HTTPS 1.2
Host: Customer configured endpoint
RPWHSecretKey: RPWH238023JSDVB23923
Content-Type: application/JSON
Accept: application/JSON
Accept-Charset: utf-8
{
   "EnvelopeId": "67d32b5e-ef28-4560-9c7a-8ba14838197e",
   "EnvelopeCode": "29602465-1772-DFEB-3729-EFFC",
   "EnvelopeStatus": "Completed",
   "FinalSignedDocument": [
      {
         "DocumentType": "SignedDocument",
         "FileType": "pdf",
         "FinalContractBase64Data": "JVBERi0xLjcKJeLjz9MKOTY"
      }
   ],
"CompletedDate": "2021-11-24 15:56:55.557",
"Timestamp": "2021-11-24 15:56:55.577",
"ReferenceCode": 12345,
"ReferenceEmail": "name@domain.com"
}

Secret Key in the API header:
The secret key configured in the RSign application for any webhook event will be sent as part of API headers.

Implementation of the Document Signed event

When any signer signs the document, then API gets triggered with the following parameters in JSON format based on the configuration:

Sample JSON payload data from the Webhook to the callback URL:

POST HTTPS 1.2
Host: Customer configured endpoint
RPWHSecretKey: RPWH238023JSDVB23923
Content-Type: application/JSON
Accept: application/JSON
Accept-Charset: utf-8
{
   "EnvelopeId": "67d32b5e-ef28-4560-9c7a-8ba14838197e",
   "EnvelopeCode": "29602465-1772-DFEB-3729-EFFC",
   "SenderEmail": "rsigncustadm@yahoo.com",
   "EnvelopeStatus": "Completed",
   "Timestamp": "2021-11-24 15:56:55.577",
   "SignerEmail": "rsignuser@yahoo.com",
   "SignerStatus": "Signed",
   "ReferenceCode": 12345,
   "ReferenceEmail": "name@domain.com"
}

Secret Key in the API header:
The secret key configured in the RSign application for any webhook event will be sent as part of API headers.

Implementation of the Signer Status event

When any signer status changes, then API gets triggered with the following parameters in JSON format based on the configuration:

Sample JSON payload data from the Webhook to the callback URL:

POST HTTPS 1.2
Host: Customer configured endpoint
RPWHSecretKey: RPWH238023JSDVB23923
Content-Type: application/JSON
Accept: application/JSON
Accept-Charset: utf-8
{
   "EnvelopeId": "67d32b5e-ef28-4560-9c7a-8ba14838197e",
   "EnvelopeCode": "29602465-1772-DFEB-3729-EFFC",
   "SenderEmail": "rsigncustadm@yahoo.com",
   "EnvelopeStatus": "Completed",
   "Timestamp": "2021-11-24 15:56:55.577",
   "SignerEmail": "rsignuser@yahoo.com",
   "SignerStatus": "Signed",
   "EnvelopeStatusOld": "Waiting for Signature",
   "ReferenceCode": 12345,
   "ReferenceEmail":"name@domain.com"
}

Secret Key in the API header:
The secret key configured in the RSign application for any webhook event will be sent as part of the API headers.

Important note: The application receiving any configured webhook MUST return a "200" StatusCode header as a response. RSign will hit the endpoint up to 5 (five) times per event while the appropriate successful response is not returned.

<back to article content