API reference / Webhooks

Webhooks

Register HTTPS endpoints to receive events, for example when a bulk job finishes. Create, list, update, test, and delete your subscriptions.

Register an HTTPS endpoint and Prime Verifier will POST a JSON event to it when something finishes, most usefully when a bulk job completes, so you never have to poll.

Event types

Event	When it fires
job.completed	A bulk verification or finder job finished; results are ready to download.
job.failed	A job stopped before completing.

◈

Verify every delivery. Each request carries an X-PV-Signature header: an HMAC-SHA256 of the raw body keyed with your webhook secret. Recompute it and compare before trusting the payload. Respond 2xx within a few seconds; we retry failures with backoff.

POST/v1/webhooksCreate a new webhook endpoint. A signing secret is auto-generated. At least one event type must be specified in the `events` array GET/v1/webhooksList all webhooks for the authenticated user PATCH/v1/webhooks/{id}Update a webhook's URL, events, or active status (partial update). Also handles toggle DELETE/v1/webhooks/{id}Delete a webhook POST/v1/webhooks/{id}/testSend a test delivery to verify the webhook URL is reachable. Only active webhooks can be tested POST/v1/webhooks/{id}/toggleUpdate a webhook's URL, events, or active status (partial update). Also handles toggle

POST/v1/webhooks

Create a new webhook endpoint. A signing secret is auto-generated. At least one event type must be specified in the `events` array

Request body application/json

Field	Type	Required
url	string · uri	required
events	WebhookEvent[]	required
isActive	boolean	optional

Returns 400, 401 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/webhooks" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }'

const res = await fetch("https://api.primeverifier.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/webhooks",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"url": "https://example.com/webhooks/prime", "events": [1], "isActive": False},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/webhooks");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com/webhooks/prime", "events" => [1], "isActive" => false]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"url":"https://example.com/webhooks/prime","events":[1],"isActive":false}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/webhooks", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { url: "https://example.com/webhooks/prime", events: [1], isActive: false }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Try itPOST /v1/webhooks

API key *

Request body (JSON)

GET/v1/webhooks

List all webhooks for the authenticated user

Returns 401 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X GET "https://api.primeverifier.com/v1/webhooks" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/webhooks", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/webhooks",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/webhooks");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/webhooks", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itGET /v1/webhooks

API key *

PATCH/v1/webhooks/{id}

Update a webhook's URL, events, or active status (partial update). Also handles toggle

Parameters

Name	In	Type	Required	Description
id	path	integer · int64	required

Request body application/json

Field	Type	Required
url	string · uri · null	optional
events	WebhookEvent[]	optional
isActive	boolean · null	optional

Returns 401, 404 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X PATCH "https://api.primeverifier.com/v1/webhooks/123" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }'

const res = await fetch("https://api.primeverifier.com/v1/webhooks/123", {
  method: "PATCH",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.patch(
    "https://api.primeverifier.com/v1/webhooks/123",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"url": "https://example.com/webhooks/prime", "events": [1], "isActive": False},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Patch, "https://api.primeverifier.com/v1/webhooks/123");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks/123"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks/123");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com/webhooks/prime", "events" => [1], "isActive" => false]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"url":"https://example.com/webhooks/prime","events":[1],"isActive":false}`)
req, _ := http.NewRequest("PATCH", "https://api.primeverifier.com/v1/webhooks/123", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks/123")
req = Net::HTTP::Patch.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { url: "https://example.com/webhooks/prime", events: [1], isActive: false }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itPATCH /v1/webhooks/{id}

API key *

id (path)

Request body (JSON)

DELETE/v1/webhooks/{id}

Delete a webhook

Parameters

Name	In	Type	Required	Description
id	path	integer · int64	required

Returns 401, 404 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X DELETE "https://api.primeverifier.com/v1/webhooks/123" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/webhooks/123", {
  method: "DELETE",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.delete(
    "https://api.primeverifier.com/v1/webhooks/123",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Delete, "https://api.primeverifier.com/v1/webhooks/123");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks/123"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks/123");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("DELETE", "https://api.primeverifier.com/v1/webhooks/123", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks/123")
req = Net::HTTP::Delete.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itDELETE /v1/webhooks/{id}

API key *

id (path)

POST/v1/webhooks/{id}/test

Send a test delivery to verify the webhook URL is reachable. Only active webhooks can be tested

Parameters

Name	In	Type	Required	Description
id	path	integer · int64	required

Returns 400, 401, 404 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/webhooks/123/test" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/webhooks/123/test", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/webhooks/123/test",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/webhooks/123/test");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks/123/test"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks/123/test");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/webhooks/123/test", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks/123/test")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itPOST /v1/webhooks/{id}/test

API key *

id (path)

POST/v1/webhooks/{id}/toggle

Update a webhook's URL, events, or active status (partial update). Also handles toggle

Parameters

Name	In	Type	Required	Description
id	path	integer · int64	required

Request body application/json

Field	Type	Required
url	string · uri · null	optional
events	WebhookEvent[]	optional
isActive	boolean · null	optional

Returns 401, 404 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/webhooks/123/toggle" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }'

const res = await fetch("https://api.primeverifier.com/v1/webhooks/123/toggle", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/prime",
    "events": [
      1
    ],
    "isActive": false
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/webhooks/123/toggle",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"url": "https://example.com/webhooks/prime", "events": [1], "isActive": False},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/webhooks/123/toggle");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/webhooks/123/toggle"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"url\":\"https://example.com/webhooks/prime\",\"events\":[1],\"isActive\":false}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/webhooks/123/toggle");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com/webhooks/prime", "events" => [1], "isActive" => false]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"url":"https://example.com/webhooks/prime","events":[1],"isActive":false}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/webhooks/123/toggle", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/webhooks/123/toggle")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { url: "https://example.com/webhooks/prime", events: [1], isActive: false }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {},
  "error": null
}

Try itPOST /v1/webhooks/{id}/toggle

API key *

id (path)

Request body (JSON)