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.

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"
  }
}

Key	Type	Description
`eventId`	`string`	The `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.
`publishedAt`	`RFC3339 timestamp as string`	Time stamp of when the event was published.
`event`	`json object`	The 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity of the application.

Application Failed event

Notifies that an application has failed.

Event

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

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity 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"
}

Key	Type	Description
`type`	`string`	Identifies the event type and current status for the application.
`applicationId`	`string`	Identity of the application.

Endpoints