Skip to main content

Webhook Setup

Webhooks allow your email service provider (ESP) to notify Score CRM about email events in real-time — deliveries, opens, clicks, bounces, complaints, and unsubscribes.

Why Webhooks Matter​

Without webhooks, Score CRM can only track:

  • Opens (via tracking pixel)
  • Clicks (via link rewriting)

With webhooks, you also get:

  • Delivery confirmations
  • Bounce notifications (hard and soft)
  • Spam complaints
  • Provider-level unsubscribes

These events are critical for suppression management, deliverability monitoring, and accurate reporting.

Webhook URL Format​

Each SMTP connection has a unique webhook URL:

https://your-domain.com/webhooks/v2/{vendor}/{connectionId}

Where:

  • {vendor} is the provider type (e.g., sendgrid, sparkpost, smtpcom)
  • {connectionId} is the unique SMTP connection ID

This URL is automatically generated when you create an SMTP connection and is displayed on the connection's detail page.

Provider-Specific Setup​

SendGrid​

  1. Log into your SendGrid dashboard
  2. Go to Settings → Mail Settings → Event Webhook
  3. Enter the webhook URL from Score CRM
  4. Select the events to receive:
    • ✅ Delivered
    • ✅ Opened
    • ✅ Clicked
    • ✅ Bounced
    • ✅ Spam Report
    • ✅ Unsubscribed
  5. Enable Signed Event Webhook for security
  6. Copy the Verification Key and add it to your SMTP connection in Score CRM as the webhook signing key
  7. Save and enable the webhook

SparkPost​

  1. Log into your SparkPost dashboard
  2. Go to Webhooks
  3. Click Create Webhook
  4. Enter the webhook URL from Score CRM
  5. Select events:
    • ✅ Delivery
    • ✅ Open
    • ✅ Click
    • ✅ Bounce
    • ✅ Spam Complaint
    • ✅ Link Unsubscribe
  6. Save the webhook
  7. Copy the authentication token to your Score CRM SMTP connection

SMTP.com​

  1. Log into your SMTP.com dashboard
  2. Navigate to Webhooks or Notifications
  3. Add the webhook URL from Score CRM
  4. Configure event types
  5. Copy the HMAC signing key to your Score CRM SMTP connection

Webhook Security​

Score CRM verifies webhook authenticity using provider-specific signature verification:

ProviderVerification Method
SendGridECDSA signature in request header
SparkPostOAuth token or webhook auth header
SMTP.comHMAC signature in request header

Always configure the signing/verification key in your SMTP connection settings to ensure only legitimate events are processed.

Event Processing​

When a webhook event is received:

  1. Receive: Score CRM receives the POST request from your ESP
  2. Verify: Signature is verified against the stored signing key
  3. Parse: Provider-specific payload is normalized to a standard event format
  4. Store: Events are processed and stored for real-time analytics
  5. Suppress: Hard bounces, complaints, and unsubscribes trigger automatic customer suppression

Troubleshooting​

IssueCheck
No events coming inVerify the webhook URL is correct in your provider's dashboard
Events rejected (401/403)Check that the signing key matches between the provider and Score CRM
Events delayedThis is normal — some providers batch webhook deliveries
Missing event typesVerify all desired event types are selected in the provider's webhook config
Duplicate eventsScore CRM handles deduplication — this is expected behavior from some providers