Webhooks

Setup a new webhook endpoint

You can subscribe to different events by creating webhook endpoints in the Settings section

You can find an up-to-date events list at the end of this page.

Configuration

Your endpoint have to respond with a success status. If it responds with a 4XX or 5XX, it will retry multiple times.

On the first fail, it will retry multiple times in the next 2 days. Your server should handle duplicates if you are queueing requests.

It will send you a warning email if it fails after ~10m.

If it fails after all these retries, it will disable your webhook and send you an email.

Payload format

The body:

{
  "event": "step_request_approved",
  "object_id": 9001,
  "object_type": "step_request",
  "fired_at": 1617885562,
  "data": {
    "data": {
      "id": "9001",
      "type": "step_request"
    }
  }
}

With:

• event : the event
• object_id : the id of the object
• object_type : the name of the object
• fired_at : timestamp when the event has been fired
• data_object : a json api payload matching the serialized object for the event. For step request events, the payload is based on ProviderStepRequest.

The headers contains 2 additional values:

• X-Hub-Timestamp, the timestamp when this webhook is sent (which can be different from fired_at in the payload)
• X-Hub-Signature, which is a base64 SHA256 of your verify token concatenate with the timestamp defined in X-Hub-Timestamp

The X-Hub-Signature enables you to verify the sender (in case someone tries to send payloads to your webhhok endpoint).

In order to calculate the X-Hub-Signature, you have to perform the following operation (example in ruby):

Digest::SHA256.base64digest("#{verify_token}#{value_in_x_hub_timestamp}")

Available events

• documents_group_to_review
• documents_group_will_expire
• documents_group_expired
• documents_group_rejected
• contact_complete
• contact_invited_to_workflow
• contact_workflow_complete
• step_request_submitted
• step_request_approved
• step_request_rejected

Available events

There's currently the following implemented events:

• > A group of documents will expire

  Code: documents_group_will_expire

  This event is triggered when a document group (which has many documents) is going to be expired in exactly one week. This event is usually triggered in the middle of the night by the system.

• > A group of documents has expired

  Code: documents_group_expired

  This event is triggered when a document group (which has many documents) is expired this day. This event is usually triggered in the middle of the night by the system.

• > A group of documents has been rejected

  Code: documents_group_rejected

  This event is triggered when a document group (which has many documents) has been rejected. This event is usually triggered when a single document is rejected (it changes the documents group status to rejected).

• > A documents group has to be reviewed

  Code: documents_group_to_review

  This event is triggered when a user uploads a file on a documents group.

• > A contact has a profile completed

  Code: contact_complete

  This event is triggered when all requests and workflows associated to a contact have been approved by someone. It's triggered immediately after a moderator action.

• > A contact has been invited to a workflow

  Code: contact_invited_to_workflow

  This event is triggered when a contact has been manually invited to a workflow

• > A contact workflow is complete

  Code: contact_workflow_complete

  This event is triggered when a contact workflow has each of this step approved or done.

• > A step request has been submitted

  Code: step_request_submitted

  This event is triggered when a contact submits a workflow step request.

• > A step request has been approved

  Code: step_request_approved

  This event is triggered when a step request has been approved by a reviewer.

• > A step request has been rejected

  Code: step_request_rejected

  This event is triggered when a step request has been rejected by a reviewer.