Webhook Events

Configure your webhook endpoints on the Bits Dashboard's Developer Page (opens in a new tab).

In order to verify the integrity of the event payload, you can set an optional secret when creating a webhook. This secret will be used to compute a HMAC signature for each event payload. The signature will be base64 encoded, and included in the Content-HMAC header of the request. You can use this signature to verify the integrity and origin of the event payload.

All webhooks will be sent as JSON and contain the payload in the body; all requests sent to you will be as a POST request.

The webhook events will provide you with notifications on the progress of your applications. You can use the ID fields in the events to fetch more information on your application using our API. Please see Endpoints.

We guarantee at-least-once delivery of events. It would be best to treat events as idempotent to avoid unwanted effects on an application. On rare occasions, you may receive duplicate events.

Versioning

As mentioned in the API Versioning section, the Bits API leverages media type versioning. Once a breaking change is introduced to the webhooks, the Content-Type header will be added to reflect the new version (since webhooks are outgoing requests from Bits to your server). The current version (without media type versioning and the Content-Type header) is v1.

Application Events

All webhook events will include a webhook envelope that wraps the actual payload.

Example Webhook envelope

{
  "eventId": "123bbc4e-5b1a-4b9e-8b9a-9b9b9b9b9b9b",
  "publishedAt": "2024-01-05T12:00:00Z",
  "event": {
    "type": "APPLICATION_STARTED",
    "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
  }
}

The event field will contain the actual event payload, and each event is identified by the type field. The section below describes the different event types.

Application Started event

Notifies that an application has been started.

Event

{
  "type": "APPLICATION_STARTED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Approved event

Notifies that an application has been approved.

Event

{
  "type": "APPLICATION_APPROVED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Pending Manual Review event

Notifies that an application is pending manual review by an underwriter.

Event

{
  "type": "APPLICATION_PENDING_MANUAL_REVIEW",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Manually Approved event

Notifies that an application has been manually approved by an underwriter.

Event

{
  "type": "APPLICATION_MANUALLY_APPROVED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Manually Declined event

Notifies that an application has been manually declined by an underwriter.

Event

{
  "type": "APPLICATION_MANUALLY_DECLINED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Failed event

Notifies that an application has failed.

Event

{
  "type": "APPLICATION_FAILED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Cancelled event

Notifies that an application has been cancelled by the applicant.

Event

{
  "type": "APPLICATION_CANCELLED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}

Application Declined event

Notifies that an application has been declined.

Event

{
  "type": "APPLICATION_DECLINED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}