Skip to main content

WebHooks

A webhook is an event notification. It is a POST request, which contains data that is posted to a specific URL. The URL defines the location of a script, which processes the data in the POST request.

Configuration​

  • Name
    Choose a name to easily identify your webhook

  • Events
    7 options:

    • user.created and/or
    • user.readyToReview and/or
    • review.approved and/or
    • user.inReview and/or
    • review.rejected and/or
    • user.blocked and/or
    • user.deleted

  • Endpoint
    The url of your choice that the webhook will request

  • Endpoint secret
    Optional but recommended. Allows to verify that the request received by the endpoint is from the expected origin.

  • Content-type
    Only application/json is supported

Events​

  • user.created
    A new profile has been submitted to the dashboard

  • user.readyToReview
    User received all required certificate and is now ready for final review.

  • review.approved
    Reviewer approved a profile in the dashboard

  • user.inReview
    Reviever turned a profile in Review

  • review.rejected
    Reviewer has rejected a profile and noticed user

  • user.blocked
    Reviewer has blocked a profile and potentially noticed user

  • user.deleted
    Reviewer has deleted a profile and potentially noticed user

Payload format​

  • X-Blockpass-Event
    Name of the event that triggered the webhook call.
  • X-Blockpass-Delivery
    Unique ID of the webhook api call. This header is used for debug purpose only
  • X-Hub-Signature
    The HMAC hex digest of the request body. This header will be sent if the webhook is configured with a secret key. The HMAC hex digest is generated using the sha256 hash function and the secret as the HMAC key. This header is used for request integrity check.

Request Body samples​

user.created​

{
  "guid": "5ffffc2dbaaaaf001236b200",
  "status": "incomplete",
  "clientId": "client_id",
  "event": "user.created",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": "rdm-1610611387861",
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

user.readyToReview​

{
  "guid": "5ffffc2dbaaaaf001236b200",
  "status": "waiting",
  "clientId": "client_id",
  "event": "user.readyToReview",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": "rdm-1610611387861",
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

review.approved​

{
  "guid": "5ffffc46baaaaf001236b209",
  "status": "approved",
  "clientId": "client_id",
  "event": "review.approved",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": "rdm-1610611387861",
  "submitCount": 1,
  "blockPassID": "5ffffaeaaaaaaaa0182f387c",
  "isArchived": false,
  "inreviewDate": "2021-01-14T08:09:39.320Z",
  "waitingDate": "2021-01-14T08:09:16.803Z",
  "approvedDate": "2021-01-14T08:09:42.508Z",
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

user.inReview​

{
  "guid": "614967cde3227d00125ebc4f",
  "status": "inreview",
  "clientId": "client_id",
  "event": "user.inReview",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": null,
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

review.rejected​

{
  "guid": "614967cde3227d00125ebc4f",
  "status": "rejected",
  "clientId": "client_id",
  "event": "review.rejected",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": null,
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

user.blocked​

{
  "guid": "614967cde3227d00125ebc4f",
  "status": "rejected",
  "clientId": "client_id",
  "event": "user.blocked",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": null,
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

user.deleted​

{
  "guid": "614967cde3227d00125ebc4f",
  "status": "deleted",
  "clientId": "client_id",
  "event": "user.deleted",
  "recordId": "5ffffb44baaaaf001236b1d1",
  "refId": null,
  "isPing": false,
  "env": "prod",
  "webhookId": null
}

Data description​

  • guid
    type: string
    Copy of X-Blockpass-Delivery

  • status
    type: string
    Status of the user in the KYC dashboard

  • clientId
    type: string
    Id of the service as defined in the Admin Console

  • event
    type: string
    Event that triggered the webhook

  • recordId
    type: string
    Id of user in the KYC dashboard. Can be used to generate url to the profile
    i.e. https://kyc.blockpass.org/kyc/dashboard/#/<clientId>/kyc_detail/<recordId>

  • refId
    type: string
    refId set in the widget. Can be used as cross-reference with an external database

  • submitCount
    type: int
    Number of times the user submitted the profile to the KYC dashboard

  • blockPassID
    type: string
    ID to share with the Blockpass support to find specific users

  • isArchived
    type: bool
    Takes 1 if profile is archived in the KYC dashboard. 0 otherwise.

  • inreviewDate
    type: string
    Timestamp of last review of the profile

  • waitingDate
    type: string
    Timestamp of last profile submission

  • approvedDate
    type: string
    Timestamp of the last approval of the profile

  • isPing
    type: bool
    Used to debug a newly created webhook, can be ignored.

  • env
    type: string
    Takes the value prod

  • webhookId
    type: string
    Used for the onprem installation of the KYC dashboard. Always null for the cloud version of the KYC dashboard

Appendix - Retrying delivery​

  • KYC Connect Dashboard considers a webhook delivery as successfull when the endpoint responds with HTTP Code 200 or 201
  • In case of a failed delivery. it will retry to invoke (maximum of 3 times), retrying interval == 10 seconds