[viniciusgiles]

Summary

The webhooks reference said only that auth_request_details.body "likely should contain the client ID, client secret, and grant type". It did not say how SparkPost sends body, so readers could not tell that they can add keys such as scope.

This change updates the Webhooks Object, Create and Update sections of content/api/webhooks.apib in the same way:

• body: SparkPost POSTs it to url with Content-Type: application/x-www-form-urlencoded, one form field per key. grant_type defaults to client_credentials. Other keys, such as scope or audience, are sent as is. An example shows a body with scope and the form it is sent as.
• url: redirects are not followed. The response must be JSON that contains access_token, and token_type, if present, must be Bearer. SparkPost then sends Authorization: Bearer <access_token> with each batch, and requests a new token when the target responds with HTTP 400 or 401.
• Update: a request that includes target, auth_request_details or custom_headers, or sets active to true, sends a test POST request. For oauth2 with new auth_request_details, SparkPost requests a new token first. A failed token request or a non-200 test response fails the update with HTTP 400. Before, the text named only target.
• The Retrieve and List response examples now show "grant_type": "client_credentials" in the stored body, as the API returns it.

Verification

• The page parses with the site's API Blueprint parser (fury-adapter-apib-parser) and gives the same warnings as main.
• Check the Netlify deploy preview at /api/webhooks/: the url and body attributes under Webhooks Object, Create a Webhook and Update a Webhook, and the paragraph under Update a Webhook.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes to the webhooks API Blueprint; no runtime or API behavior changes.

Overview
Expands the Event Webhooks API reference for OAuth 2.0 auth_request_details so integrators know how SparkPost actually calls the token endpoint and uses the result.

The url and body field descriptions are rewritten consistently on the Webhooks Object, Create, and Update sections: token requests use the token URL directly (redirects fail), expect JSON with access_token (and Bearer if token_type is set), attach Authorization: Bearer … on webhook batches, and refresh tokens on 400/401. The body is sent as application/x-www-form-urlencoded, with default grant_type of client_credentials and support for extra keys such as scope or audience, including a concrete form-encoded example.

Update a Webhook now documents when a validation test POST runs (not only on target changes): also when auth_request_details, custom_headers, or active: true are involved, with OAuth token fetch before the test when auth_request_details changes. Retrieve/list response examples add "grant_type": "client_credentials" in stored auth_request_details.body.

^{Reviewed by Cursor Bugbot for commit a6111db. Bugbot is set up for automated code reviews on this repo. Configure here.}