Documentation

Zapier, Make and n8n

REST hooks, the polling fallback, and what an automation is deliberately not allowed to do.

Every outgoing event can reach Zapier, Make, n8n or anything else that accepts a signed POST. There are two ways in, and which one you want depends on whether you are writing your own integration or configuring somebody else's platform.

If you are writing your own integration

Use POST /api/v1/webhooks. It takes an event list and returns a signing secret, and you verify deliveries with verifyWebhook from @proudpass/sdk. See Webhooks.

If you are configuring an iPaaS

Use the REST-hook pair. Every one of these platforms implements the same contract: subscribe with one target URL for one event, keep the id, DELETE it later.

POST /api/v1/hooks
Authorization: Bearer <api key>

{ "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc", "event": "credential.published" }
{ "success": true, "data": { "id": "whe_...", "event": "credential.published" } }
DELETE /api/v1/hooks/whe_...

Three things about this pair are deliberate:

  • It is idempotent. An iPaaS retries aggressively, and a retried subscribe that created a second hook would make every event fire twice.
  • DELETE answers 200 even when the hook is already gone. Otherwise turning a Zap off would start a retry loop against a resource that is never coming back.
  • It does not return the signing secret. These platforms have nowhere to run a signature check, so handing them a secret would only put it in stored connection data where nobody treats it as one. If you need verified delivery, use /v1/webhooks.

It is still one WebhookEndpoint, one retry schedule and one signing path underneath. A second copy of the backoff and the lease is two chances to get them wrong.

Scopes

Scope Needed for
webhooks:write Subscribing and unsubscribing
webhooks:read Listing subscriptions
credentials:read The polling sample and lookups
credentials:issue Only if the automation issues

Create a key with the narrowest set that works. A Zap that watches for published credentials has no business issuing or revoking.

What an automation cannot do

It cannot publish. credentials:issue and credentials:publish are separate scopes, and the Zapier app only ever asks for the first. Anything that creates a credential from outside the dashboard issues into review.

This is the single most important rule in this page. Publishing consumes a credit, emails the recipient and fires the webhook — so a misconfigured automation that could publish is one that charges you and mails strangers, triggered by a rule somebody set up weeks ago. Releasing stays a human act.

Idempotency when issuing

The Zapier action sends an Idempotency-Key derived from the Zap run. Do the same in your own automation: an iPaaS retries on any network failure, including one where our response was lost after the credential was already created. Without a key, that retry issues a second credential for the same person. See Idempotency.

Events worth watching, and two to avoid

Watch credential.published, credential.revoked, credential.renewed, credential.expired and credential.accepted.

Avoid two:

  • credential.verified fires on every public check. On a popular credential that is thousands of runs a day, and it tells you nothing new each time. Read the figures from Insights instead.
  • credential.issued fires for a credential still in review, which is almost never what "when a certificate is awarded" means.

The app definition

Lives in integrations/zapier in the repository, deliberately outside the pnpm workspace — a Zapier app is deployed with Zapier's own CLI to Zapier's infrastructure, and turbo build cannot build it. Its README has the push instructions.