Webhooks Overview

Receive the result of a registration, verification, or identification job at your server as a signed HTTPS event, instead of polling.

What are webhooks?

Registration, verification, and identification are asynchronous jobs. Without webhooks, your server polls the job until it leaves PENDING. With webhooks, Petify sends one signed HTTPS POST to your server when a job finishes, with the result in the body.

Webhooks are available on every plan. You set them up yourself in the Petify Console.

Webhooks do not replace the job endpoints. The poll endpoint (GET /v2/.../jobs/{jobId}) stays the authoritative source for a job's status. Use webhooks to learn about results sooner, and poll to recover anything you missed. See Delivery & Retries.

Jobs created by a hosted session send no webhook events today. Sessions issued for Web Integration (link or server integration) complete through the redirect and the result code instead. Webhooks cover jobs you create through the Server API.

How it works

Your server starts a job through the API, as before.
When the job reaches SUCCESS or FAILED, Petify sends an event to every enabled endpoint that subscribes to that event type.
Your endpoint verifies the signature, processes the event, and answers with a 2xx status.
If your endpoint does not answer 2xx, Petify retries on a fixed schedule.

Quick start in the Console

Build an HTTPS endpoint that accepts POST requests with a JSON body. Start from the signature verification samples.
In the Petify Console, open Integration and select the Webhooks tab.
Click Add endpoint.
Enter the Endpoint URL. Optionally add a Description (up to 200 characters).
Under Events, select the event types you want, or select All events (including ones added later). Select at least one.
Click Add endpoint to save. The Console shows the signing secret (whsec_...) once in a dialog. Copy it and store it safely, for example in your secret manager.
Open the endpoint and click Send test event. Petify sends one signed webhook.test event and shows whether your endpoint answered with a 2xx status.

You can read the signing secret again at any time: open the endpoint and click Reveal secret.

Manage endpoints

Action	What it does
Add endpoint	Creates an endpoint that starts enabled, with a new signing secret.
Edit	Changes the URL, description, or subscribed events. The signing secret stays the same. A subscription change applies to events sent after you save.
Enabled switch	Turns the endpoint on or off. While it is off, matching events are recorded as Skipped and not sent. See Disabled endpoints.
Reveal secret / Rotate secret	Shows the current signing secret, or creates a new one. After a rotation the previous secret keeps signing for 24 hours. See Rotating the secret.
Send test event	Sends one signed `webhook.test` event now, even if the endpoint is disabled. It is not retried and does not appear in the delivery log.
Delete	Removes the endpoint and its delivery log. This cannot be undone.

Endpoint requirements and limits

Item	Rule
URL scheme	`https` only.
Host	Must be reachable from the public internet. Private and local addresses (for example `localhost` or `10.x.x.x`) are refused.
URL length	Up to 500 characters.
Description	Optional, up to 200 characters.
Endpoints per account	Up to 5. Delete one to add another.
Redirects	Not followed. A `3xx` answer counts as a failed attempt.
Response time	Answer within 10 seconds.
Request headers	`User-Agent: Petify-Webhooks/1`, plus the signature headers.

If several endpoints subscribe to the same event type, each one receives the event with the same body and the same webhook-id.

Next steps

Events & Payloads - Event types and example bodies
Verify Signatures - Code samples for Node.js and Python
Delivery & Retries - Retry schedule, duplicates, resend, and the delivery log