Skip to content
KnockDevelopers
Webhooks

Ping a webhook

Chat with a Developer
post/v1/webhooks/{webhookId}/ping

No “Try it” here: this call changes data. Run the code samples from your own backend.

Sends a webhook.ping event to the webhook now and returns what your endpoint answered. A ping is never retried. You can ping each webhook once every 10 seconds, paused ones too.

Needs an API key with the Admin role.

Authorization

ApiKeyAuth
headerx-api-key<token>

Your Knock API key. Reading webhooks takes a key with read access to integrations: the Admin, Editor, Viewer, CRM Admin or AI Manager role (not an Enrichment API key). Changing them takes a key with the Admin role.

Path Parameters

webhookId*string

ID of the webhook.

Formatuuid

Response Body

Knock sent the ping. delivered says whether your endpoint accepted it.

application/json
  1. response

What happened to the webhook.ping Knock sent, to a webhook or to a URL under test.

eventId*string

ID of the ping event: its webhook-id header and body id. Knock does not record a URL test, so its ID only helps you find the request in your own logs.

Formatuuid
delivered*boolean

Whether your endpoint answered with a 2xx status.

statusCode*|

The status your endpoint answered. Null when it gave no HTTP response.

errorCode*|

Null when delivered. Otherwise why not:

  • http_status: your endpoint answered a status other than 2xx or 3xx.
  • redirect: your endpoint answered a 3xx: Knock does not follow redirects.
  • timeout: no response within 5 seconds.
  • connection: the connection failed or was closed.
  • dns: the host name did not resolve.
  • tls: the TLS handshake or certificate check failed.
  • blocked_destination: the host resolves to an address that is not public.
Value in"http_status""redirect""timeout""connection""dns""tls""blocked_destination"null
durationMs*integer

How long the request took, in milliseconds.

retryAfterSeconds*integer

Seconds before Knock accepts another ping of this webhook, or another URL test of your account (one sent sooner gets a 429). 0 when you can send one now.

Range0 <= value
Example Request
curl -X POST 'https://app.knock-ai.com/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/ping' \  -H 'x-api-key: <YOUR_API_KEY>'
Example Response
{  "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",  "delivered": true,  "statusCode": 0,  "errorCode": "http_status",  "durationMs": 0,  "retryAfterSeconds": 0}

Delete a webhook DELETE

Deletes a webhook.