POST/webhook-endpoints
Registers an HTTPS endpoint to receive signed webhook events. The response carries the signing secret, the only time it is returned.
pf-api-keyRate limit: 180 requests per hourStore the secret now
secret is in this response and nowhere else: no other route returns it. If you lose it, delete the endpoint and create a new one.
Before you register
A workspace can have 5 active endpoints. Disabled ones do not count. If you need more, ask support.
Each endpoint receives the events you pick for the whole workspace, so one endpoint per integration is usually enough.
A URL can be registered more than once: each registration is a separate endpoint with its own secret. If a create call fails without a response, check GET /webhook-endpoints before you try again, because the endpoint may already exist.
Events, signature verification and delivery rules are under /docs/webhooks.
Request body
urlstringrequiredHTTPS URL of your receiver, up to 2,048 characters. It must use port 443 and a public hostname: the full rules are under /docs/webhooks#registering.
eventsstring[]requiredThe events to receive: 1 to 4 of these, each once. webhook.test cannot be subscribed to.
post.publishedpost.failedaccount.connectedaccount.disconnecteddescriptionstringoptionalYour own label for the endpoint, up to 255 characters.
Errors
| Status | message | When |
|---|---|---|
400 | webhook.invalidUrl | The url is not a URL PostFast can read, or it is null on an update. |
400 | webhook.urlNotHttps | The url is not https. |
400 | webhook.urlHostNotAllowed | The hostname is an IP address, localhost, has no dot, or uses an internal suffix such as .local or .internal, or the URL carries credentials. |
400 | webhook.urlPortNotAllowed | The url uses a port other than 443. |
400 | webhook.urlPrivateAddress | The hostname resolves to an address that is not public. |
400 | webhook.urlResolutionFailed | The hostname does not resolve. |
400 | webhook.limitReached | The workspace already has 5 active endpoints. Applies when creating an endpoint and when re-enabling one. |
Other problems with the body (a missing url, an unknown or repeated event, a description that is too long) return the usual validation 400, with message as an array of strings.
Response
201 Created The new endpoint, with its signing secret.
idstring (UUID)requiredThe endpoint's id. Every other route takes it.
workspaceIdstring (UUID)requiredThe workspace the API key belongs to.
urlstringrequiredWhere PostFast sends events, as stored: a query string is kept and a #fragment is dropped.
eventsstring[]requiredThe events this endpoint receives. Never empty.
post.publishedpost.failedaccount.connectedaccount.disconnecteddescriptionstring | nulloptionalYour own label for the endpoint.
activebooleanrequiredWhether PostFast sends events to this endpoint.
disabledReasonstring | nulloptionalWhy PostFast turned the endpoint off: GONE (the receiver answered 410) or FAILING (it kept failing, see /docs/webhooks#delivery). null while it is active, and when you turned it off yourself with active: false.
GONEFAILINGlastSuccessAtISO 8601 | nulloptionalWhen a delivery to this endpoint last succeeded.
lastFailureAtISO 8601 | nulloptionalWhen a delivery to this endpoint last failed.
createdAtISO 8601requiredWhen the endpoint was created.
updatedAtISO 8601requiredWhen the endpoint last changed.
secretstringrequiredThe signing secret (whsec_...). This response is the only time it is returned.