Introduction

​

Overview

Webhooks provide real-time notifications about screening status changes in your application process. Instead of requiring you to continuously poll our API for updates, webhooks push notifications directly to your specified endpoint whenever there’s a change in an applicant’s screening status.

​

Getting Started

​

1. Register Your Webhook Endpoint

To start receiving webhook notifications, please provide your webhook endpoint URL to: concierge@cove.co

You will receive:

• A webhook endpoint configuration
• A webhook secret for security verification

Your endpoint should be:

• Publicly accessible over HTTPS
• Capable of handling POST requests
• Able to respond with a 200 OK status code

​

2. Security

All webhook requests will:

• Be sent over HTTPS
• Include an HMAC signature in the X-HMAC-SIGNATURE header
• Be signed using your webhook secret
• Have Content-Type: application/json header

To verify webhook authenticity, compute the HMAC signature of the raw request body using your webhook secret and compare it with the X-HMAC-SIGNATURE header value.

​

Webhook Payload

Each webhook notification includes a JSON payload with the following structure:

{
    "time": "2025-02-03T12:26:56-05:00",
    "applicant": {
        "id": "app_123456789",
        "status": "USER_COMPLETED"
    },
    "org": {
        "id": "org_987654321"
    },
    "property": {
        "id": "prop_123456"
    },
    "listor": {
        "id": "lst_789012"
    }
}

​

Payload Fields

• time: Timestamp when the event occurred
• applicant: Information about the applicant
  • id: Unique identifier for the applicant
  • status: Current status of the screening (see Status Values)
• org: Organization information
  • id: Organization identifier
• property: Property information
  • id: Property identifier
• listor: Listor information
  • id: Listor identifier

​

Best Practices

1. Verify Signatures: Always verify the HMAC signature using your webhook secret before processing the payload.

2. Respond Quickly: Return a 200 OK response as soon as you receive and verify the webhook. Process the data asynchronously if needed.

3. Handle Retries: Your endpoint should be idempotent as the same webhook may be sent multiple times in case of delivery failures.

4. Store Raw Payload: Save the raw webhook data before processing it, in case you need to debug issues later.

​

Testing

You can test your webhook integration by providing a test endpoint to concierge@cove.co. We’ll help you simulate webhook events to verify your integration.

​

Support

If you have any questions or need assistance with webhook integration, please contact:

• Email: concierge@cove.co
• Documentation: API Reference

We aim to respond to all webhook-related inquiries within one business day.