Webhooks

curl https://api.mobilevalidate.com/v1/webhook_endpoints \
  -H "Authorization: Bearer mv_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/mobilevalidate","events":["lookup.completed","job.completed","job.failed"]}'

// Node.js 18+, Deno, Bun or the browser console (ES module: save as .mjs or use "type": "module").
const res = await fetch("https://api.mobilevalidate.com/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    Authorization: "Bearer mv_test_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/mobilevalidate",
    events: ["lookup.completed", "job.completed", "job.failed"],
  }),
});
console.log(res.status, res.headers.get("x-request-id"));
console.dir(await res.json(), { depth: null });

// Node.js 18+, Deno, Bun or the browser console (ES module: save as .mjs or use "type": "module").
const res = await fetch("https://api.mobilevalidate.com/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    Authorization: "Bearer mv_test_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/mobilevalidate",
    events: ["lookup.completed", "job.completed", "job.failed"],
  }),
});
console.log(res.status, res.headers.get("x-request-id"));
console.dir(await res.json(), { depth: null });

# pip install requests
import requests

res = requests.post(
    "https://api.mobilevalidate.com/v1/webhook_endpoints",
    headers={"Authorization": "Bearer mv_test_YOUR_KEY"},
    json={
        "url": "https://hooks.example.com/mobilevalidate",
        "events": ["lookup.completed", "job.completed", "job.failed"],
    },
    timeout=30,
)
print(res.status_code, res.json())

<?php
$ch = curl_init('https://api.mobilevalidate.com/v1/webhook_endpoints');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer mv_test_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://hooks.example.com/mobilevalidate',
        'events' => ['lookup.completed', 'job.completed', 'job.failed'],
    ]),
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), PHP_EOL, $response, PHP_EOL;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"url":"https://hooks.example.com/mobilevalidate","events":["lookup.completed","job.completed","job.failed"]}`)
	req, err := http.NewRequest("POST", "https://api.mobilevalidate.com/v1/webhook_endpoints", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer mv_test_YOUR_KEY")
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

require "net/http"
require "json"

uri = URI("https://api.mobilevalidate.com/v1/webhook_endpoints")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer mv_test_YOUR_KEY"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  "url" => "https://hooks.example.com/mobilevalidate",
  "events" => ["lookup.completed", "job.completed", "job.failed"]
})

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.code, res.body

{"type": "job.completed", "id": "evt_…", "created_at": "2026-09-25T14:30:02Z",
 "data": {"object": "job", "id": "job_…", "status": "completed",
          "progress": {"total": 3, "checks_total": 9, "done": 9, "conclusive": 6, "non_billable": 3},
          "results_url": "https://api.mobilevalidate.com/v1/jobs/job_…/results"}}

{"type": "lookup.completed", "id": "evt_…", "created_at": "2026-09-25T14:30:05Z",
 "data": {"object": "lookup", "id": "lkp_…", "status": "completed", "livemode": true,
          "summary": {"total": 1, "registered": 1, "not_registered": 0, "unknown": 0}}}
``` Fetch the rows with your key. Treat `id` as the idempotency key for your handler, because retries can deliver the same event more than once.

## How do I verify the signature?

Each delivery has three headers:

| Header | Content |
|---|---|
| `webhook-id` | The event id (same across retries) |
| `webhook-timestamp` | Unix seconds when this attempt was sent |
| `webhook-signature` | `v1,<base64 HMAC-SHA256>` of `${webhook-id}.${webhook-timestamp}.${raw body}` |

The HMAC key is the base64-decoded part of the secret after `whsec_`. Use the **raw** request body, not re-serialised JSON. Reject timestamps more than 5 minutes from your clock, and compare signatures in constant time:

```js title="verify-webhook.mjs (Node.js 18+, ES module)"
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigHeader = headers["webhook-signature"] ?? "";
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error("stale or missing headers");
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  const ok = sigHeader.split(" ").some((part) => {
    const [version, sig] = part.split(",");
    const got = Buffer.from(sig ?? "", "base64");
    return version === "v1" && got.length === expected.length && timingSafeEqual(got, expected);
  });
  if (!ok) throw new Error("invalid signature");
  return JSON.parse(rawBody);
}