Webhooks

Which endpoints use webhooks#

How it works#

1. You include a webhookUrl in your API request
2. The API immediately returns HTTP 200 with {"status": "in progress"} — this is an acknowledgment, not the result
3. Ocean.io processes the request in the background
4. When complete, Ocean.io sends a POST request to your webhookUrl with Content-Type: application/json
5. Your server must return a 2xx status code to acknowledge receipt

Webhook endpoint requirements#

Your webhook receiver must:

• Be publicly reachable over HTTPS
• Return a 2xx HTTP status code (e.g., 200 OK) within a reasonable timeout
• Be idempotent — the same payload may be delivered more than once if retries occur

If your endpoint returns a non-2xx status or times out, Ocean.io will retry with exponential backoff.

Payload formats#

Enrich Companies (Batch) and Enrich People (Batch)#

Results are keyed by the IDs you provided in companyDataMapping or peopleDataMapping:

{
  "results": {
    "your-id-001": {
      "status": "found",
      "company": { "...enriched company object..." }
    },
    "your-id-002": {
      "status": "not_found",
      "company": null
    },
    "your-id-003": {
      "status": "triggered",
      "company": null
    }
  }
}

For Enrich People, company is replaced by person.

Reveal Emails#

{
  "results": [
    {
      "personId": "abc123",
      "email": {
        "address": "[email protected]",
        "status": "verified"
      }
    },
    {
      "personId": "def456",
      "email": {
        "address": null,
        "status": "notFound"
      }
    }
  ]
}

Reveal Phones#

{
  "results": [
    {
      "personId": "abc123",
      "phone": {
        "numbers": ["+4512345678"],
        "status": "verified"
      }
    }
  ]
}

Email and phone status values#

Idempotency#

The same payload may be delivered more than once if your endpoint doesn't acknowledge in time. Deduplicate on the record IDs in the payload and return 2xx as fast as possible — offload heavy processing to a background queue.

Security#

Ocean.io sends from a fixed set of IP addresses — contact support for the current range if you want to allowlist them.

Alternatively, include a secret token in your webhookUrl:

https://yourapp.com/webhooks/ocean?secret=MY_SECRET_TOKEN

Validate this token in your webhook handler before processing any payload.

Delivery timing#

Times vary with server load and domain accessibility.