​
Webhooks Overview

Webhooks allow your application to receive real-time updates from ContactManager when specific events occur. Instead of polling our API for changes, webhooks deliver information to your server as events happen.

​
How Webhooks Work

  1. You register a webhook URL in your ContactManager dashboard
  2. When an event occurs (like a user follows another user), ContactManager sends an HTTP POST request to your URL
  3. Your server processes the event data and responds appropriately

​
Getting Started with Webhooks

​
Step 1: Set Up Your Webhook Endpoint

Create an endpoint on your server that can receive POST requests. This endpoint will receive webhook payloads containing event data.

​
Step 2: Register Your Webhook

  1. Go to https://dash.contactsmanager.io/webhooks
  2. Click “Add Webhook”
  3. Enter your endpoint URL
  4. Select which events you want to receive
  5. Save your webhook configuration

​
Step 3: Generate a Webhook Secret

For security, ContactManager signs all webhook requests with a secret key. You’ll verify this signature to ensure requests are legitimate.

  1. On the webhook configuration page, generate a new webhook secret
  2. Store this secret securely in your application environment
  3. Use this secret to verify incoming webhook payloads

​
Step 4: Handle Webhook Events

When your endpoint receives a webhook request, you’ll need to:

  1. Verify the request signature using your webhook secret
  2. Process the event based on its type
  3. Return a 2xx response promptly (we recommend 200 OK)

​
SDK Integration

For easier implementation, our SDKs include built-in webhook verification:

​
Retry Logic

ContactManager implements automatic retry logic for webhook deliveries:

  • If your endpoint returns a non-2xx response or times out, we’ll retry the webhook
  • Retries follow an exponential backoff schedule:
    • First retry: 3 seconds after the initial attempt
    • Second retry: 7 seconds after the first retry
  • We make a maximum of 3 attempts (initial attempt + 2 retries)
  • Each delivery attempt is logged with its status for debugging

This retry mechanism ensures reliable delivery even if your endpoint experiences temporary issues.

​
Security Best Practices

  • Always verify webhook signatures
  • Process webhooks asynchronously
  • Use HTTPS for your webhook endpoint
  • Implement retry logic for failed webhook processing
  • Store raw webhook payloads for debugging

​
Next Steps