API - Webhooks | Surfe Help Center

Surfe Webhooks: Real-Time Notifications Made Simple

What is a webhook?

Think of a webhook as a "special messenger" that automatically sends you data the moment something important happens. So you don’t have to keep checking manually. It’s like a notifier that does the worrying for you.

How Does It Work? Three Simple Steps

You give us a URL This is like giving us an address where we can send a message. It's called your webhook endpoint — a public URL that can accept a message (a POST request) from us.
An event happens For example, Surfe might finish enriching a contact. When that's done, we automatically send the info to your URL, no polling required.
You say "Got it!" Your server needs to reply with a 200 OK — that's your way of saying, "Thanks, I received the data." If you send something else, we might try sending it again based on your settings.

Your webhook URL must use HTTPS. HTTP URLs are not accepted and will be rejected by Surfe. Make sure your endpoint starts with https:// before adding it to your request.

What Event Can I Get Notified About?

Right now, Surfe supports two events:

person.enrichment.completed — This tells you when a contact's enrichment is done. It includes useful information like their name, email, job title, and more.

When this event happens and you provided a webhookUrl, Surfe sends:

{
  "eventType": "person.enrichment.completed",
  "data": {
    "enrichmentID": "0198c820-d5f1-7c7f-a9f7-a19fc24846t7",
    "person": {
      "externalID": "Webhooktest-id",
      "firstName": "David",
      "lastName": "Chevalier",
      "companyName": "Surfe",
      "companyDomain": "surfe.com",
      "linkedInUrl": "https://linkedin.com/in/david-maurice-chevalier",
      "jobTitle": "Co-Founder & CEO",
      "location": "Paris, Île-de-France",
      "country": "France",
      "emails": [
        {
          "email": "d.c@surfe.com",
          "validationStatus": "VALID"
        }
      ],
      "mobilePhones": [
        {
          "mobilePhone": "+491111113211",
          "confidenceScore": 0.95
        }
      ],
      "status": "COMPLETED"
    }
  }
}

This structure gives you everything you need to process the enriched data — no polling needed.

company.enrichment.completed — Get notified when Surfe finishes enriching details about a company, like their name, website, size, industry, and more.

When this event happens and you provided a webhookUrl, Surfe sends:

{
  "eventType": "company.enrichment.completed",
  "data": {
    "enrichmentID": "01973b15-68d2-7937-b87c-78dd0069b2db",
    "company": {
      "externalID": "your-internal-id",
      "name": "Surfe",
      "websites": ["surfe.com"],
      "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.",
      "employeeCount": 65,
      "founded": "2020",
      "hqAddress": "52 Rue Chaussée D'antin Paris FR 75009",
      "hqCountry": "FR",
      "industry": "IT Services",
      "subIndustry": "Internet Services & Infrastructure",
      "revenue": "10-50M",
      "linkedInURL": "https://linkedin.com/company/surfe",
      "isPublic": false,
      "followersCountLinkedin": 8896,
      "digitalPresence": [
        {
          "name": "LinkedIn",
          "url": "https://www.linkedin.com/company/surfe"
        }
      ],
      "fundingRounds": [
        {
          "amount": 9999999,
          "amountCurrency": "$",
          "announcedDate": "2021-01-01",
          "leadInvestors": ["Investor A", "Investor B"],
          "name": "Seed Round - Surfe"
        }
      ],
      "keywords": [
        "crm updates",
        "linkedin sales",
        "waterfall enrichment",
        "sales automation"
      ],
      "status": "COMPLETED"
    }
  }
}

Why Use Webhooks Instead of Polling?

Automatic: No manual checking. You get updates right away.
Efficient: Your system isn't kept busy asking for info over and over again.
Light on resources: Saves you time and computing power.

How to Set It Up in Plain English

When you send your enrichment request, include a webhookUrl inside notificationOptions.
Make sure your server can accept POST requests and respond quickly with 200 OK.
Handle the data when it arrives — maybe store it, process it, or trigger another action.

Setting up a people enrichment webhook:

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

Once the enrichment is done, you'll receive the person.enrichment.completed payload at your webhook endpoint.

Setting up a company enrichment webhook:

curl -X POST "https://api.surfe.com/v2/companies/enrich" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {
        "domain": "surfe.com",
        "externalID": "your-internal-id"
      }
    ],
    "notificationOptions": {
      "webhookUrl": "https://your-server.com/webhook"
    }
  }'

Once complete, you'll receive the company.enrichment.completed payload at your webhook endpoint.

Summary Table

When You Do This…	Then This Happens…
Provide a `webhookUrl`	Surfe sends updates automatically when enrichment completes
Your server returns `200 OK`	Surfe knows you’ve received the data successfully
You receive the payload in your system	You can then use or store the enriched information