API reference
Webhooks
Register one endpoint per account to receive pushed notices such as a revoked grant. Read the Webhooks page for what the signature header can and cannot show you.
DELETE /v1/webhooks
Remove the registration
Removes the endpoint; queued deliveries to it are dropped at the next drain.
Parameters
None.
Request body
None.
Example request
curl
curl -sS -X DELETE "https://api.afaprotocol.com/v1/webhooks" \
-H "X-API-Key: afa-beta-EXAMPLE-e4qs"Python
import requests
API = "https://api.afaprotocol.com"
headers = {"X-API-Key": "afa-beta-EXAMPLE-e4qs"}
r = requests.delete(f"{API}/v1/webhooks", headers=headers, timeout=30)
r.raise_for_status()
print(r.json())Example response
HTTP 200
{
"deleted": true,
"user_id": "2f6e1a0c-9b4d-4e8a-8c31-5d7f0a2b9c14"
}Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_token / invalid_or_expired_api_key | No credential, an expired session, or a revoked or expired key. |
| 403 | scope_missing | A key limited by scopes lacks webhooks; the body names it. |
What would show this is false
Delete twice: the second answers deleted false. The first removed it and the second found nothing.
GET /v1/webhooks
Current registration
Shows whether an endpoint is registered and which URL.
Parameters
None.
Request body
None.
Example request
curl
curl -sS -X GET "https://api.afaprotocol.com/v1/webhooks" \
-H "X-API-Key: afa-beta-EXAMPLE-e4qs"Python
import requests
API = "https://api.afaprotocol.com"
headers = {"X-API-Key": "afa-beta-EXAMPLE-e4qs"}
r = requests.get(f"{API}/v1/webhooks", headers=headers, timeout=30)
r.raise_for_status()
print(r.json())Example response
HTTP 200
{
"configured": true,
"url": "https://hooks.example.com/afa/7f3a1c"
}Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_token / invalid_or_expired_api_key | No credential, an expired session, or a revoked or expired key. |
| 403 | scope_missing | A key limited by scopes lacks webhooks; the body names it. |
What would show this is false
The response carries no secret. Until it does, the X-AFA-Signature header cannot be recomputed on your side; the Webhooks page says what to do instead.
PUT /v1/webhooks
Register the endpoint
Registers or replaces the one URL that receives pushed notices for this account.
Parameters
None.
Request body
urlstring required- No description in the schema.
Example request
curl
curl -sS -X PUT "https://api.afaprotocol.com/v1/webhooks" \
-H "X-API-Key: afa-beta-EXAMPLE-e4qs" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/afa/7f3a1c"
}'Python
import requests
API = "https://api.afaprotocol.com"
headers = {"X-API-Key": "afa-beta-EXAMPLE-e4qs"}
payload = {
"url": "https://hooks.example.com/afa/7f3a1c"
}
r = requests.put(f"{API}/v1/webhooks", headers=headers, json=payload, timeout=30)
r.raise_for_status()
print(r.json())Example response
HTTP 200
{
"configured": true,
"url": "https://hooks.example.com/afa/7f3a1c",
"user_id": "2f6e1a0c-9b4d-4e8a-8c31-5d7f0a2b9c14"
}Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_token / invalid_or_expired_api_key | No credential, an expired session, or a revoked or expired key. |
| 403 | scope_missing | A key limited by scopes lacks webhooks; the body names it. |
| 422 | validation error | A required field is missing or a value has the wrong type. |
| 422 | webhook url must be an absolute http(s) URL | Refused and not stored, so a dead registration can never exist. |
What would show this is false
Register ftp://example.com: 422, and GET /v1/webhooks still shows the previous registration.