Surfe API
Get API KeySupportGive feedback

Webhooks

A webhook is a way for one system to send real-time data to another system as soon as an event happens. Instead of constantly checking (polling) for updates, a webhook lets your application receive updates automatically.

Think of it like a notification system: when something important happens, the system calls your provided URL (usually an API endpoint) with the event data.

How to Use a Webhook

  1. Provide a URL: You give the system a public URL (your webhook endpoint) that can receive POST requests.
  2. Wait for Events: When a specific event occurs (like a person enrichment completing), the system sends a request to your URL with the relevant data.
  3. Handle the Request: Your server processes the data and responds with a 200 OK to confirm receipt.

Example Use Case

You want to be notified when a person's enrichment is completed. You provide a webhookUrl in the request. Once the enrichment is done, we send a POST request to your URL with the result data.

This approach is efficient, reduces load on your system, and gives you near-instant updates.

Supported event types

Example notification event:

    enum EventType {
        PersonEnrichmentCompleted  = "person.enrichment.completed"
        CompanyEnrichmentCompleted = "company.enrichment.completed"
    }
    export interface Event {
        eventType: EventType;
        data: any;
    }

"person.enrichment.completed"

Will be triggered when a contact within a bulk enrichment has been completed.

Source: POST /v2/people/enrich

If the notificationOptions.webhookUrl field is set, our server will send a POST request to that URL each time a person enrichment is completed.

To acknowledge successful receipt of the event, your server should respond with an HTTP 200 OK. If a different status is returned, we may retry the request depending on your configuration.

The request body sent by our server will include the details of the completed person enrichment, as shown below:

Request Body

application/jsonRequired
eventTypeRequiredstring
Value in: "person.enrichment.completed"
dataRequiredobject

Example webhook request from our server to your server

{
  "eventType": "person.enrichment.completed",
  "data": {
    "enrichmentID": "01973f39-f391-7b75-8812-7aad73f798f6",
    "person": {
      "companyDomain": "surfe.com",
      "companyName": "Surfe",
      "country": "France",
      "departments": [
        "Engineering",
        "R&D"
      ],
      "emails": [
        {
          "email": "david.chevalier@surfe.com",
          "validationStatus": "VALID"
        }
      ],
      "externalID": "external-id",
      "firstName": "David",
      "jobTitle": "Co-Founder & CEO",
      "lastName": "Chevalier",
      "linkedInUrl": "https://www.linkedin.com/in/david-maurice-chevalier",
      "location": "Paris, Île-de-France",
      "mobilePhones": [
        {
          "confidenceScore": 0.8,
          "mobilePhone": "+33 6 12 34 56 78"
        }
      ],
      "seniorities": [
        "Manager",
        "Head"
      ],
      "status": "COMPLETED"
    }
  }
}

Note that the data.person field is of type EnrichedPersonResponse, the same type used in the people field of the GET /v2/people/enrich/:id endpoint.

Example enrichment request with webhookUrl provided

 
curl -X POST "https://api.surfe.com/v2/people/enrich" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "include": {
      "email": true,
      "linkedInUrl": false,
      "mobile": false
    },
    "notificationOptions": {
      "webhookUrl": "https://webhook.site/d17b3a76-2336-4c18-8de9-7b44096f62b3"
    },
    "people": [
      {
        "companyDomain": "surfe.com",
        "companyName": "Surfe",
        "externalID": "external-id",
        "firstName": "David",
        "lastName": "Chevalier",
        "linkedinUrl": "https://www.linkedin.com/in/david-maurice-chevalier"
      }
    ]
  }'

"company.enrichment.completed"

Will be triggered when a company within a bulk enrichment has been completed.

Source: POST /v2/company/enrich

If the notificationOptions.webhookUrl field is set, our server will send a POST request to that URL each time a company enrichment is completed.

To acknowledge successful receipt of the event, your server should respond with an HTTP 200 OK. If a different status is returned, we may retry the request depending on your configuration.

The request body sent by our server will include the details of the completed person enrichment, as shown below:

Request Body

application/jsonRequired
eventTypeRequiredstring
Value in: "company.enrichment.completed"
dataRequiredobject

Example webhook request from our server to your server

{
 "eventType": "company.enrichment.completed",
 "data": {
  "enrichmentID": "01973b15-68d2-7937-b87c-78dd0069b2db",
  "company": {
   "externalID": "external-id",
   "name": "Surfe",
   "description": "Sales teams waste too much time on repetitive admin tasks. Surfe handles everything before the phone call - identifying target accounts, building lead lists, and enriching data. Our mission is to empower sales teams, automating the essential steps of the workflow while enhancing the human touch. Trusted by 3,000+ companies from local to global GTM needs like Google, Uber, AWS, Bolt, Pigment. Compatible with HubSpot, Salesforce, Pipedrive, and Copper CRM. As a GDPR-compliant and ISO27001-certified tool, Surfe helps your team operate from a gold standard of data, making sure everything is structured, categorized, updated, and protected. Surfe has been selected as Top 100 fastest-growing products on G2 and recognized as a Top 100 Rising European Startups by VivaTech in 2025.",
   "linkedInURL": "https://linkedin.com/company/surfe",
   "websites": [
    "surfe.com"
   ],
   "founded": "2020",
   "revenue": "10-50M",
   "employeeCount": 65,
   "keywords": [
    "crm updates",
    "reply rate",
    "linkedin sales",
    "linkedin messages",
    "synchronize linkedin",
    "contact data",
    "increase",
    "linkedin sources",
    "linkedin profiles",
    "email finder",
    "contact lists",
    "subscribing",
    "crm",
    "linked prospecting",
    "linkedin",
    "verified emails",
    "databases",
    "contact enrichment",
    "top-performing",
    "demo",
    "add prospects",
    "email addresses",
    "email lookup",
    "meetings",
    "professional email",
    "inmails",
    "emails",
    "top-performing sales",
    "prospecting",
    "average",
    "email",
    "real-time access",
    "enrich contacts",
    "rate",
    "marketing outbound",
    "secure crm",
    "contact",
    "highest reply",
    "contacts",
    "receive updates",
    "sales navigator",
    "france"
   ],
   "hqCountry": "FR",
   "hqAddress": "52 Rue Chaussée D'antin, Paris, 75009, FR",
   "industry": "IT Services",
   "subIndustry": "Internet Services & Infrastructure",
   "phones": [
    ""
   ],
   "digitalPresence": [
    {
     "name": "LinkedIn",
     "url": "https://www.linkedin.com/company/surfe"
    },
    {
     "name": "Twitter",
     "url": "https://twitter.com/surfehq"
    },
    {
     "name": "Facebook",
     "url": "https://www.facebook.com/surfehq"
    },
    {
     "name": "Instagram",
     "url": "https://www.instagram.com/surfehq/"
    }
   ],
   "fundingRounds": [
    {
     "name": "Seed Round - Surfe",
     "amount": 9999999999,
     "amountCurrency": "$",
     "announcedDate": "2021-01-01",
     "leadInvestors": [
      "Investor A",
      "Investor B"
     ]
    }
   ],
   "ipo": {
    "date": "2021-01-01",
    "sharePrice": 999999999,
    "sharePriceCurrency": "$"
   },
   "isPublic": false,
   "followersCountLinkedin": 8896,
   "status": "COMPLETED"
  }
 }
}

Note that the data.company field is of type EnrichedCompanyResponse, the same type used in the company field of the GET /v2/company/enrich/:id endpoint.

Example enrichment request with webhookUrl provided

 
curl -X POST "https://api.surfe.com/v2/company/enrich" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {
        "domain": "surfe.com",
        "externalID": "external-id"
      }
    ],
    "notificationOptions": {
      "webhookUrl": "https://webhook.site/d17b3a76-2336-4c18-8de9-7b44096f62b3"
    },
  }'

Secure your endpoint

You should secure your webhook integration and verify that all webhook requests are coming from Surfe. You can verify webhook signatures using your webhook shared secret key. You can find your secret key in the API settings. The key becomes available once you’ve received your first webhook notification.

To help add to the security of webhook communication, usage of https endpoints is required.

❌ Not valid, insecure http URL:

"notificationOptions": {
      "webhookUrl": "http://insecure-surfe-webhook.com"
    },

✅ Valid, secure https URL:

"notificationOptions": {
      "webhookUrl": "https://secure-surfe-webhook.com`"
    },

How to Verify Surfe Webhook Signatures

To ensure webhook requests are genuinely sent by Surfe and have not been tampered with, each webhook event includes an x-surfe-signature header. The signature contains 2 parts, a timestamp prefixed with t= and the signature scheme prefixed by v0=.

x-surfe-signature:
t=1758468698287,
v0=ac18feb8cdbcaf4bf98beb90586f95159646a21629326f8bb6f63305f82155ea
#(a real signature is a single line)

Surfe generates signatures using hash-based message authentication code HMAC with SHA-256.

Follow these steps to verify the signature:

Step 1: Extract timestamp and signature from the header

Split the header using the , character as the separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v0 corresponds to the signature. You can discard all other elements.

Step 2: Recreate the signed payload

The signed_payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (that is, the request body)

Step 4: Compute the HMAC Hash

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 5: Compare Signatures

Compare the computed signature with the value in the x-surfe-signature header. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Step 6: Accept or Reject the Request

If the signatures match, process the webhook.

Code examples

Python

import hmac
import hashlib
 
def verify_webhook_signature(payload, secret, signature_header):
    parts = signature_header.split(',')
    timestamp = ''
    signature = ''
    for part in parts:
        if part.startswith('t='):
            timestamp = part.replace('t=', '')
        if part.startswith('v0='):
            signature = part.replace('v0=', '')
    if not timestamp or not signature:
        raise ValueError('invalid signature header format')
 
    # Recreate the signed message
    message = f"{timestamp}.{payload}"
 
    # Compute HMAC
    mac = hmac.new(secret.encode(), message.encode(), hashlib.sha256)
    expected_signature = mac.hexdigest()
 
    print("Expected signature:", expected_signature)
    print("Received signature:", signature)
 
    return hmac.compare_digest(expected_signature, signature)
 
shared_secret = "<YOUR_SHARED_SECRET>"
signature_header = "t=1758503642403,v0=4ff48a2e4767453781f153ad1e15453809d8d90795a840477894d8592bffd79f"
payload = '{"eventType":"person.enrichment.completed","data":{"enrichmentID":"01996efb-b83b-7e8a-89cf-7a1ad6e92cc9","person":{"externalID":"external-id","firstName":"David","lastName":"Chevalier","companyName":"Surfe","companyDomain":"surfe.com","linkedInUrl":"https://linkedin.com/in/david-maurice-chevalier","emails":[],"mobilePhones":[],"status":"COMPLETED"}}}'
 
try:
    valid = verify_webhook_signature(payload, shared_secret, signature_header)
    if valid:
        print("Signature is valid")
    else:
        print("Signature is invalid")
except Exception as e:
    print(e)

Javascript

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, secret, signatureHeader) {
  const parts = signatureHeader.split(',');
  let timestamp = '';
  let signature = '';
  for (const part of parts) {
    if (part.startsWith('t=')) {
      timestamp = part.replace('t=', '');
    }
    if (part.startsWith('v0=')) {
      signature = part.replace('v0=', '');
    }
  }
  if (!timestamp || !signature) {
    throw new Error('invalid signature header format');
  }
 
  // Recreate the signed message
  const message = `${timestamp}.${payload}`;
 
  // Compute HMAC
  const hmacObj = crypto.createHmac('sha256', secret);
  hmacObj.update(message);
  const expectedSignature = hmacObj.digest('hex');
 
  console.log('Expected signature:', expectedSignature);
  console.log('Received signature:', signature);
 
  return expectedSignature === signature;
}
 
const sharedSecret = '<YOUR_SHARED_SECRET>';
const signatureHeader = 't=1758503642403,v0=4ff48a2e4767453781f153ad1e15453809d8d90795a840477894d8592bffd79f';
const payload = '{"eventType":"person.enrichment.completed","data":{"enrichmentID":"01996efb-b83b-7e8a-89cf-7a1ad6e92cc9","person":{"externalID":"external-id","firstName":"David","lastName":"Chevalier","companyName":"Surfe","companyDomain":"surfe.com","linkedInUrl":"https://linkedin.com/in/david-maurice-chevalier","emails":[],"mobilePhones":[],"status":"COMPLETED"}}}';
 
try {
  const valid = verifyWebhookSignature(payload, sharedSecret, signatureHeader);
  if (valid) {
    console.log('Signature is valid');
  } else {
    console.log('Signature is invalid');
  }
} catch (err) {
  console.error(err.message);
}

Golang

package main
 
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"strings"
)
 
func main() {
	sharedSecret := "<YOUR_SHARED_SECRET>"
	signatureHeader := "t=1758503642403,v0=4ff48a2e4767453781f153ad1e15453809d8d90795a840477894d8592bffd79f"
	payload := `{"eventType":"person.enrichment.completed","data":{"enrichmentID":"01996efb-b83b-7e8a-89cf-7a1ad6e92cc9","person":{"externalID":"external-id","firstName":"David","lastName":"Chevalier","companyName":"Surfe","companyDomain":"surfe.com","linkedInUrl":"https://linkedin.com/in/david-maurice-chevalier","emails":[],"mobilePhones":[],"status":"COMPLETED"}}}`
 
	valid, err := VerifyWebhookSignature(payload, sharedSecret, signatureHeader)
	if err != nil {
		// handle error
	}
	if valid {
		// signature is valid
		fmt.Println("Signature is valid")
	} else {
		// signature is invalid
		fmt.Println("Signature is invalid")
	}
}
 
// VerifyWebhookSignature verifies the HMAC signature for a webhook payload.
func VerifyWebhookSignature(payload any, secret string, signatureHeader string) (bool, error) {
	parts := strings.Split(signatureHeader, ",")
	var timestamp, signature string
	for _, part := range parts {
		if strings.HasPrefix(part, "t=") {
			timestamp = strings.TrimPrefix(part, "t=")
		}
		if strings.HasPrefix(part, "v0=") {
			signature = strings.TrimPrefix(part, "v0=")
		}
	}
	if timestamp == "" || signature == "" {
		return false, errors.New("invalid signature header format")
	}
 
	// Recreate the signed message
	message := timestamp + "." + string(payload.(string))
 
	// Compute HMAC
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(message))
	expectedMAC := mac.Sum(nil)
	expectedSignature := hex.EncodeToString(expectedMAC)
 
	fmt.Println("Expected signature:", expectedSignature)
	fmt.Println("Received signature:", signature)
	return hmac.Equal([]byte(expectedSignature), []byte(signature)), nil
}

Preventing replay attacks

A replay attack occurs when someone captures a legitimate webhook payload and its signature, then tries to resend (replay) it to your endpoint. To help prevent this, Surfe adds a timestamp to the x-surfe-signature header. Since the timestamp is included in the data that is signed, any attempt to alter it will break the signature verification. If you receive a valid signature but the timestamp is outside your allowed time window, your application should reject the request as potentially malicious.

Previous

Responses & Errors

Next

Changelog

On this page