Webhooks API | TestingBot API Documentation

GET /v1/webhooks

List your webhooks

Returns every webhook on the team. Webhooks fire when a test finishes; use failure_only, alert_types and name_filter to narrow which tests trigger a delivery. The signing secret is never returned here — it is shown once when the webhook is created or its secret is rotated.

Arguments

offset integer: Skip this many webhooks from the start of the result set.
count integer: Number of webhooks to return.

Response fields

data array of webhook objects: Webhooks on this team.
meta meta object: —

    GET
    /v1/webhooks
  

        cURL
    Request

        
  
  $ curl "https://api.testingbot.com/v1/webhooks?offset=0&count=10" \
-u key:secret

    Response

  
  {
  "data": [
    {
      "id": 50,
      "name": "CI notifier",
      "url": "https://example.com/hooks/testingbot",
      "http_method": "POST",
      "failure_only": true,
      "alert_types": "ALL",
      "name_filter": null,
      "auth_type": "NONE",
      "headers": [{ "key": "X-Source", "value": "testingbot" }],
      "params": [],
      "payload_template": null,
      "created_at": "2026-08-03T10:00:32.000Z",
      "updated_at": "2026-08-03T10:00:32.000Z"
    }
  ],
  "meta": { "offset": 0, "count": 10, "total": 1 }
}

GET /v1/webhooks/{id}

Get a specific webhook

Returns a single webhook by ID. Receiver credentials and the signing secret are never included.

Arguments

id integer required: Numeric webhook ID.

Response fields

id integer: Unique numeric webhook ID.
name string: Label for the webhook, shown on the dashboard.
url string: Destination URL. May contain {{VARIABLES}}, which are substituted at delivery time.
http_method string: HTTP method used to deliver: POST, PUT or PATCH.
failure_only boolean: When true, only failed tests trigger a delivery.
alert_types string: Which grid the test ran on: ALL, VIRTUAL (VM) or REAL (physical device).
name_filter string: Glob matched against the test name, falling back to the build identifier. Empty means every test.
auth_type string: How the request authenticates against your endpoint: NONE, BASIC or BEARER. The credentials themselves are never returned.
headers array of object: Custom request headers, each { "key": ..., "value": ... }. Values support {{VARIABLES}}.
params array of object: Custom query parameters appended to the URL, each { "key": ..., "value": ... }.
payload_template string: Custom JSON body template. Empty means the default TestingBot payload is sent.
created_at timestamp: When the webhook was created.
updated_at timestamp: When the webhook was last changed.
signing_secret string: Secret used to verify the X-TestingBot-Signature header. Only present when the webhook is created or its secret is rotated; store it then, because it is never returned again.

    GET
    /v1/webhooks/{id}
  

        cURL
    Request

        
  
  $ curl "https://api.testingbot.com/v1/webhooks/{id}" \
-u key:secret

    Response

  
  {
  "id": 50,
  "name": "CI notifier",
  "url": "https://example.com/hooks/testingbot",
  "http_method": "POST",
  "failure_only": true,
  "alert_types": "ALL",
  "name_filter": null,
  "auth_type": "NONE",
  "headers": [{ "key": "X-Source", "value": "testingbot" }],
  "params": [],
  "payload_template": null,
  "created_at": "2026-08-03T10:00:32.000Z",
  "updated_at": "2026-08-03T10:00:32.000Z"
}

POST /v1/webhooks

Create a webhook

Creates a webhook. The response includes signing_secret — the only time it is ever returned — which you use to verify the X-TestingBot-Signature header on deliveries. A team may have at most 5 webhooks.

Arguments

url string required: Destination URL. Must be a public http(s) address; private, loopback and link-local hosts are rejected.
name string: Label for the webhook. Required once the extended webhook columns are present.
http_method string: HTTP method used to deliver. Defaults to POST.
failure_only boolean: Deliver only for failed tests. Defaults to false.
alert_types string: Which grid to report on: ALL, VIRTUAL or REAL.
name_filter string: Glob matched against the test name, falling back to the build identifier.
auth_type string: How to authenticate against your endpoint: NONE, BASIC or BEARER.
auth_username string: Username for BASIC auth. Write-only, never returned.
auth_password string: Password for BASIC auth. Write-only, never returned.
auth_token string: Token for BEARER auth. Write-only, never returned.
headers array: Custom request headers, each an object with key and value.
params array: Custom query parameters appended to the URL, each an object with key and value.
payload_template string: Custom JSON body template using {{VARIABLES}}. Omit to send the default TestingBot payload.

    POST
    /v1/webhooks
  

        cURL
    Request

        
  
  $ curl -X POST "https://api.testingbot.com/v1/webhooks" \
-u key:secret \
-H "Content-Type: application/json" \
-d '{
  "name": "CI notifier",
  "url": "https://example.com/hooks/testingbot",
  "failure_only": true,
  "alert_types": "ALL",
  "headers": [{ "key": "X-Source", "value": "testingbot" }]
}'

    Response

  
  {
  "id": 50,
  "name": "CI notifier",
  "url": "https://example.com/hooks/testingbot",
  "http_method": "POST",
  "failure_only": true,
  "alert_types": "ALL",
  "name_filter": null,
  "auth_type": "NONE",
  "headers": [{ "key": "X-Source", "value": "testingbot" }],
  "params": [],
  "payload_template": null,
  "created_at": "2026-08-03T10:00:32.000Z",
  "updated_at": "2026-08-03T10:00:32.000Z",
  "signing_secret": "whsec_a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

PUT /v1/webhooks/{id}

Update a webhook

Updates a webhook. Only the fields you send are changed. Sending auth_password or auth_token replaces the stored value; omitting them leaves it alone. The signing secret is not returned — rotate it if you have lost it.

Arguments

id integer required: Numeric webhook ID.
url string: Destination URL. Must be a public http(s) address.
name string: Label for the webhook.
http_method string: HTTP method used to deliver.
failure_only boolean: Deliver only for failed tests.
alert_types string: Which grid to report on: ALL, VIRTUAL or REAL.
name_filter string: Glob matched against the test name, falling back to the build identifier.
auth_type string: How to authenticate against your endpoint.
auth_username string: Username for BASIC auth. Write-only.
auth_password string: Password for BASIC auth. Write-only.
auth_token string: Token for BEARER auth. Write-only.
headers array: Custom request headers, each an object with key and value. Replaces the existing set.
params array: Custom query parameters, each an object with key and value. Replaces the existing set.
payload_template string: Custom JSON body template. Send an empty string to go back to the default payload.

Response fields

id integer: Unique numeric webhook ID.
name string: Label for the webhook, shown on the dashboard.
url string: Destination URL. May contain {{VARIABLES}}, which are substituted at delivery time.
http_method string: HTTP method used to deliver: POST, PUT or PATCH.
failure_only boolean: When true, only failed tests trigger a delivery.
alert_types string: Which grid the test ran on: ALL, VIRTUAL (VM) or REAL (physical device).
name_filter string: Glob matched against the test name, falling back to the build identifier. Empty means every test.
auth_type string: How the request authenticates against your endpoint: NONE, BASIC or BEARER. The credentials themselves are never returned.
headers array of object: Custom request headers, each { "key": ..., "value": ... }. Values support {{VARIABLES}}.
params array of object: Custom query parameters appended to the URL, each { "key": ..., "value": ... }.
payload_template string: Custom JSON body template. Empty means the default TestingBot payload is sent.
created_at timestamp: When the webhook was created.
updated_at timestamp: When the webhook was last changed.
signing_secret string: Secret used to verify the X-TestingBot-Signature header. Only present when the webhook is created or its secret is rotated; store it then, because it is never returned again.

    PUT
    /v1/webhooks/{id}
  

        cURL
    Request

        
  
  $ curl -X PUT "https://api.testingbot.com/v1/webhooks/{id}" \
-u key:secret \
-H "Content-Type: application/json" \
-d '{ "name": "CI notifier (failures only)", "failure_only": true }'

    Response

  
  {
  "id": 50,
  "name": "CI notifier (failures only)",
  "url": "https://example.com/hooks/testingbot",
  "http_method": "POST",
  "failure_only": true,
  "alert_types": "ALL",
  "name_filter": null,
  "auth_type": "NONE",
  "headers": [{ "key": "X-Source", "value": "testingbot" }],
  "params": [],
  "payload_template": null,
  "created_at": "2026-08-03T10:00:32.000Z",
  "updated_at": "2026-08-03T10:04:11.000Z"
}

DELETE /v1/webhooks/{id}

Delete a webhook

Permanently deletes the webhook. Deliveries stop immediately; tests already in flight will not fire it.

Arguments

id integer required: Numeric webhook ID.

    DELETE
    /v1/webhooks/{id}
  
        cURL
    Request

  $ curl -X DELETE "https://api.testingbot.com/v1/webhooks/{id}" \
-u key:secret

    Response

  {
  "success": true,
  "message": "Webhook \"https://example.com/hooks/testingbot\" deleted."
}

POST /v1/webhooks/{id}/rotate-secret

Rotate a webhook signing secret

Issues a new signing secret and returns it. The previous secret stops verifying immediately, so update your receiver before rotating in production. This is the only other time the secret is returned.

Arguments

id integer required: Numeric webhook ID.

    POST
    /v1/webhooks/{id}/rotate-secret
  
        cURL
    Request

  $ curl -X POST "https://api.testingbot.com/v1/webhooks/{id}/rotate-secret" \
-u key:secret

    Response

  {
  "id": 50,
  "signing_secret": "whsec_f0e9d8c7b6a5948372615f4e3d2c1b0a"
}

POST /v1/webhooks/{id}/test

Send a test delivery

Delivers a sample payload to the webhook right now and returns what your endpoint responded, so you can verify the URL, authentication and signature verification without waiting for a test to finish. Sample data is used, not a real test result. Rate limited separately from the rest of the API.

Arguments

id integer required: Numeric webhook ID.

    POST
    /v1/webhooks/{id}/test
  

        cURL
    Request

        
  
  $ curl -X POST "https://api.testingbot.com/v1/webhooks/{id}/test" \
-u key:secret

    Response

  
  {
  "ok": true,
  "status": 200,
  "duration_ms": 148,
  "headers": { "content-type": "application/json" },
  "body": "{\"received\":true}",
  "sent_payload": "{\"id\":1,\"status\":\"FAILED\",\"name\":\"MyTest::testTitle\"}"
}