API
Webhook Events

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"
  }
}
KeyTypeDescription
eventIdstringThe eventId is a unique identifier for the event. It is used to ensure that you do not process the same event more than once. If you receive an event with a eventId you have already seen, you should ignore it and not process it again.
publishedAtRFC3339 timestamp as stringTime stamp of when the event was published.
eventjson objectThe webhook event body. See following section on available event body types.

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"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

Application Approved event

Notifies that an application has been approved.

Event

{
  "type": "APPLICATION_APPROVED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

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"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

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"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

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"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

Application Failed event

Notifies that an application has failed.

Event

{
  "type": "APPLICATION_FAILED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

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"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.

Application Declined event

Notifies that an application has been declined.

Event

{
  "type": "APPLICATION_DECLINED",
  "applicationId": "bits:application::79421f52-c35e-4b7f-8282-8d3b0caa1f50"
}
KeyTypeDescription
typestringIdentifies the event type and current status for the application.
applicationIdstringIdentity of the application.