API reference
Change a subscription's events, URL, profile filter or enabled state.
https://api.betterpost.dev/v1/notifications/{id}Only the fields you send change. The secret stays the same.
| Name | Description |
|---|---|
id | The subscription id. |
| Field | Type | Required | Description |
|---|---|---|---|
eventTypes | array | No | Replaces the subscribed events (one or more, unique). |
webhook.url | string | No | New public https URL. |
profileId | string or null | No | New profile filter; null for the whole project. |
onlyScheduledPosts | boolean | No | |
enabled | boolean | No | false pauses deliveries. |
No other fields are accepted; channel cannot be changed.
curl -s -X PATCH https://api.betterpost.dev/v1/notifications/ntf_6w2h9k4b1q7s3e8d0f5g2j4l \
-H "x-access-key: $BETTERPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": false, "onlyScheduledPosts": true }'200 OK
{
"success": true,
"notification": {
"id": "ntf_6w2h9k4b1q7s3e8d0f5g2j4l",
"channel": "webhook",
"profileId": null,
"eventTypes": [
"post.published",
"post.partial",
"post.failed"
],
"onlyScheduledPosts": true,
"enabled": false,
"webhook": {
"url": "https://app.example.com/webhooks/betterpost",
"secret": "whsec_••••0sFa"
},
"lastTestAt": null,
"lastTestStatus": null,
"createdAt": "2026-10-21T15:30:00.000Z",
"updatedAt": "2026-10-21T16:02:41.117Z"
}
}| Status | Code | When |
|---|---|---|
200 | The subscription was updated. | |
400 | validation_error | An invalid or unknown field. |
400 | invalid_url | The new URL is not https or not public. |
400 | channel_not_supported | Email settings were sent. |
401 | unauthorized | Missing or unknown API key. |
429 | rate_limited | More than 120 requests per minute. |
404 | not_found | No such subscription, or profileId does not exist. |