Skip to main content
Wiza sends webhook notifications to your server when enrichment requests complete. This lets you process results asynchronously without polling the API. When a request finishes (or fails), Wiza sends a POST request to your configured URL with the enrichment results.

​
Setting Up Your Webhook URL

Configure your default webhook URL in Settings → API. This URL applies to all API requests made with that key. You can also enable Send All Callbacks to receive webhooks for all enrichment activity on your account, not just requests made through the API.
Your webhook endpoint must be publicly accessible and return a 200 status code to acknowledge receipt.

​
Handling Webhook Requests

Respond quickly with a 200 status code to acknowledge receipt. If your processing takes time, accept the webhook first and handle the work asynchronously in a background job. Use status.code to check for success (200) or failure (400). For the full response schema, see the Individual Reveal documentation. 
app.post('/webhook', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process asynchronously
  const { status, data } = req.body;

  if (status.code === 200) {
    processReveal(data);
  }
});

​
Overriding the Webhook URL Per Request

You can override the default webhook URL on a per-request basis by including a callback_url parameter in your Start Individual Reveal request. 
{
  "individual_reveal": {
    "profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/"
  },
  "enrichment_level": "partial",
  "callback_url": "https://your-server.com/webhook"
}

​
Webhook Payload

Endpoint: POST {your_webhook_url} Wiza sends a webhook when an Individual Reveal completes or fails. The request is a POST with a Content-Type: application/json header sent to your configured URL or the callback_url specified in the request. The data object contains the same enrichment results as the corresponding GET endpoint. Individual Reveal Payload: 
{
  "status": {
    "code": 200,
    "message": "Single reveal finished"
  },
  "type": "individual_reveal",
  "data": {
    "id": 123456,
    "status": "finished",
    "is_complete": true,
    "name": "Stephen Hakami",
    "company": "Wiza",
    "enrichment_level": "partial",
    "linkedin_profile_url": "https://www.linkedin.com/in/stephen-hakami-5babb21b0/",
    "title": "Founder, Chief Executive Officer",
    "location": "Toronto, Ontario, Canada",
    "email": "stephen@wiza.co",
    "email_type": "work",
    "email_status": "valid",
    "emails": [
      {
        "email": "stephen@wiza.co",
        "email_type": "work",
        "email_status": "valid"
      }
    ],
    "credits": {
      "email_credits": 1,
      "phone_credits": 0,
      "export_credits": 0,
      "api_credits": {
        "total": 2,
        "email_credits": 2,
        "phone_credits": 0,
        "scrape_credits": 1
      }
    }
  }
}
Failed Request Payload: When a request fails, the status.code will be 400. The data object contains the same fields as a successful response, with a fail_error field indicating the failure reason. 
{
  "status": {
    "code": 400,
    "message": "Single reveal failed"
  },
  "type": "individual_reveal",
  "data": {
    "id": 123456,
    "status": "failed",
    "fail_error": "..."
  }
}

​
Verifying Webhook Signatures

Webhook requests include an x-auth-key header containing a SHA256 hash of your API key. Use this to verify the request originated from Wiza. 
const crypto = require('crypto');

function verifyWebhook(request, apiKey) {
  const receivedHash = request.headers['x-auth-key'];
  const expectedHash = crypto
    .createHash('sha256')
    .update(apiKey)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedHash),
    Buffer.from(expectedHash)
  );
}

​
Retry Behavior

If your webhook endpoint returns a non-2xx response, Wiza will retry up to 3 times. Ensure your endpoint is available and returns a 200 status code to acknowledge receipt.
If a webhook consistently fails (returns 404 or 403), Wiza will stop retrying for that request.