Test a webhook

Sends a sample payload to the URL you specify, using your account's signing and OAuth 2 settings. This test is optional.

Test webhook payload:

{
    "message": "this is a test webhook"
}

URL checks

Before sending the payload, this endpoint checks the URL in the order below. If a check fails, you get a 400, the remaining checks do not run, and the test payload is not sent.

  1. The scheme must be http or https. Otherwise, the error key is error.validation.WebhookUrlScheme. Scheme names are not case-sensitive.
  2. The URL must be valid. Otherwise, the error key is error.validation.ValidWebhookUrl.
  3. This endpoint sends one HEAD request to your URL:
    • If the host resolves only to IANA special-purpose IPv4 addresses, no request is sent and the error key is error.validation.ValidWebhookUrl.
    • If the server presents a TLS certificate that is expired, untrusted, or does not match the host name, the error key is error.validation.WebhookCertificate.
    • Any HTTP status code passes, because the server responded.
    • If the request gets no HTTP response, the URL still passes and the test result reports the failure.

http and https

We recommend an https URL. Webhooks to an https URL use TLS 1.2 or higher.

This endpoint accepts an http URL. Webhook configurations need allow_insecure_http for an http URL, but the test does not.

Signing and OAuth 2

  • If your account has an active signing secret, this endpoint signs the test payload.
  • If your account has an OAuth 2 credential, this endpoint requests a new access token and sends it with the test payload. If the token request fails, the test payload is not sent and the test result reports the token failure.
  • Over http, the traffic is unencrypted, and signed payloads and OAuth 2 tokens are never sent.

Response

A negative server_response_code means the service got no HTTP response or did not send the payload.

Permissions

You need the "Create and update webhooks" permission to use this endpoint.

Body Params
uri
required

The URL to send the test payload to. The scheme must be http or https, and the host must not resolve only to IANA special-purpose IPv4 addresses. For an https URL, the TLS certificate must match the host name, be trusted, and not be expired. See "URL checks" in the endpoint description.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json