Notifications
Signed HTTPS notifications for visitor storage writes on Simple Host and Simple Hack.
GET /v1/hack/events/{slug}/website/notifications
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes |
Responses:
| Status | Description |
|---|---|
| 200 | List notifications for a site; an empty list returns 200, including an authorised Hack website not yet published |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
POST /v1/hack/events/{slug}/website/notifications
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | string | Opaque key for a create request. For 24 hours, the same authenticated account, POST path and query, key and exact request body replay the original handler status and body, including errors, without executing it again. A different body under that key returns 409 idempotency_key_reused. Concurrent identical requests wait for the first response. Stored only in this server’s memory; a restart clears it. Authentication and rate limiting still apply to replays. A replay does not extend a minted link’s expiry; use a new key to request a new link. Storage row creates support owner credentials and signed-in visitors; anonymous writes ignore this header. Storage replay also checks current resource permissions and is scoped to the resolved site. | |
| slug | path | string | yes |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| auth_header | object | ||
| events | array of string, one of record.added, record.changed, file.uploaded, site.deployed, domain.status_changed, viewer.access_requested, visitor.signed_up |
yes | |
| label | string | ||
| secret | string | ||
| storage | string | Existing site storage resource; empty means all resources. | |
| url | string | yes | HTTPS, at most 2048 bytes, no userinfo or fragment. Every resolved address must be public. Redirects are not followed. |
Responses:
| Status | Description |
|---|---|
| 201 | Create an owner-made notification |
| 400 | invalid_url, refused_address, invalid_events, invalid_secret, invalid_header, or storage_not_found. |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | too_many_notifications: the site subscription cap is reached. notifications_not_enabled: the server has no PASSCODE_ENC_KEY. |
PATCH /v1/hack/events/{slug}/website/notifications/{id}
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| paused | boolean | yes | true pauses; false resumes a paused or suspended subscription and makes held deliveries due now. |
Responses:
| Status | Description |
|---|---|
| 200 | Pause or resume a notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
DELETE /v1/hack/events/{slug}/website/notifications/{id}
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
Responses:
| Status | Description |
|---|---|
| 200 | Remove a notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
GET /v1/hack/events/{slug}/website/notifications/{id}/deliveries
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
Responses:
| Status | Description |
|---|---|
| 200 | List recent notification deliveries |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
POST /v1/hack/events/{slug}/website/notifications/{id}/rotate-secret
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
Responses:
| Status | Description |
|---|---|
| 200 | Rotate an owner-made signing secret |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | client_secret: the client manages this MCP subscription secret. notifications_not_enabled: the server has no PASSCODE_ENC_KEY. |
POST /v1/hack/events/{slug}/website/notifications/{id}/test
Manage your own subscriptions for this custom event website through your current organiser role. Creation and delivery end when the event ends. Lists, history, and deletion remain available. Signing, sealed secrets, limits, tests, and rotation use the shared notification engine.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| slug | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
Responses:
| Status | Description |
|---|---|
| 200 | Send a signed test notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | client_subscription: test sends require an unexpired owner-made subscription. |
| 503 | busy: ten verification or test sends are already running. |
GET /v1/notifications
Owner credentials required on Host. On Hack, use a personal credential for your approved team membership; subscriptions belong to the person, not the holding account.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Responses:
| Status | Description |
|---|---|
| 200 | List notifications across the account |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
GET /v1/sites/{sitename}/notifications
Owner credentials required on Host. On Hack, use a personal credential for your approved team membership; subscriptions belong to the person, not the holding account.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Responses:
| Status | Description |
|---|---|
| 200 | List notifications for a site; an empty list returns 200, including an authorised Hack website not yet published |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
POST /v1/sites/{sitename}/notifications
The owner-entered URL is accepted without an MCP verification challenge. Generates a secret unless one is supplied; the response shows it once. Optional custom header and svix-* aliases are sent only for owner-made subscriptions. MCP and REST share the site subscription cap. On Hack, new subscriptions require approved membership before the team submission deadline; deliveries and existing refreshes continue afterward. Leaving, removal, moves, or loss of approval delete the affected subscriptions.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | string | Opaque key for a create request. For 24 hours, the same authenticated account, POST path and query, key and exact request body replay the original handler status and body, including errors, without executing it again. A different body under that key returns 409 idempotency_key_reused. Concurrent identical requests wait for the first response. Stored only in this server’s memory; a restart clears it. Authentication and rate limiting still apply to replays. A replay does not extend a minted link’s expiry; use a new key to request a new link. Storage row creates support owner credentials and signed-in visitors; anonymous writes ignore this header. Storage replay also checks current resource permissions and is scoped to the resolved site. | |
| sitename | path | string | yes | |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| auth_header | object | ||
| events | array of string, one of record.added, record.changed, file.uploaded, site.deployed, domain.status_changed, viewer.access_requested, visitor.signed_up |
yes | |
| label | string | ||
| secret | string | ||
| storage | string | Existing site storage resource; empty means all resources. | |
| url | string | yes | HTTPS, at most 2048 bytes, no userinfo or fragment. Every resolved address must be public. Redirects are not followed. |
Responses:
| Status | Description |
|---|---|
| 201 | Create an owner-made notification |
| 400 | invalid_url, refused_address, invalid_events, invalid_secret, invalid_header, or storage_not_found. |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | too_many_notifications: the site subscription cap is reached. notifications_not_enabled: the server has no PASSCODE_ENC_KEY. |
PATCH /v1/sites/{sitename}/notifications/{id}
false also resumes suspension and makes held deliveries due now. Owner credentials required. On Hack, new subscriptions require approved membership before the team submission deadline; deliveries and existing refreshes continue afterward. Leaving, removal, moves, or loss of approval delete the affected subscriptions.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Request body:
| Name | Type | Required | Description |
|---|---|---|---|
| paused | boolean | yes | true pauses; false resumes a paused or suspended subscription and makes held deliveries due now. |
Responses:
| Status | Description |
|---|---|
| 200 | Pause or resume a notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
DELETE /v1/sites/{sitename}/notifications/{id}
Owner credentials required on Host. On Hack, use a personal credential for your approved team membership; subscriptions belong to the person, not the holding account.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Responses:
| Status | Description |
|---|---|
| 200 | Remove a notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
GET /v1/sites/{sitename}/notifications/{id}/deliveries
Newest first, at most 200 within the configured history window (default 7 days). Pending deliveries are held while suspended. Five attempts by default; HTTP 410/413 and refused addresses are not retried. On Hack, new subscriptions require approved membership before the team submission deadline; deliveries and existing refreshes continue afterward. Leaving, removal, moves, or loss of approval delete the affected subscriptions.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Responses:
| Status | Description |
|---|---|
| 200 | List recent notification deliveries |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
POST /v1/sites/{sitename}/notifications/{id}/rotate-secret
Shows the new secret once. Deliveries carry signatures for both secrets for 24 hours, until previous_valid_until, or drops the previous secret if it cannot be read. An MCP subscription must refresh events/subscribe with a new secret instead. On Hack, new subscriptions require approved membership before the team submission deadline; deliveries and existing refreshes continue afterward. Leaving, removal, moves, or loss of approval delete the affected subscriptions.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Responses:
| Status | Description |
|---|---|
| 200 | Rotate an owner-made signing secret |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | client_secret: the client manages this MCP subscription secret. notifications_not_enabled: the server has no PASSCODE_ENC_KEY. |
POST /v1/sites/{sitename}/notifications/{id}/test
Sends notification.test with data {v:1, site, site_url, test:true}; webhook-id starts with evt_test_. The response reports the HTTP status and result category, never the receiver body. Test sends require an unexpired owner-made subscription and do not appear in delivery history. Challenge and test sends share limits of 10/minute per owner, host, and resolved IP, with at most 10 running at once. On Hack, new subscriptions require approved membership before the team submission deadline; deliveries and existing refreshes continue afterward. Leaving, removal, moves, or loss of approval delete the affected subscriptions.
Auth: an API key (X-API-Key header, or a REST-audience connector token as Authorization: Bearer).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sitename | path | string | yes | |
| id | path | string | yes | Subscription ID from the notification list. |
| event | query | string | Hack event slug for a team site. Required when the person belongs to same-named teams in multiple events; the connector supplies it from the selected team. |
Responses:
| Status | Description |
|---|---|
| 200 | Send a signed test notification |
| 401 | Missing or invalid owner credentials. |
| 403 | forbidden, or notification_access_ended when membership or the creation window no longer permits the operation. |
| 404 | not_found, or not_offered for an event account. |
| 409 | client_subscription: test sends require an unexpired owner-made subscription. |
| 503 | busy: ten verification or test sends are already running. |