Create Webhook
Register an organization webhook endpoint, select supported event types, and capture the signing secret returned once.
Endpoint contract
Use the exact method and path shown above. Paths are relative to the API base URL.
Authentication, permission, and scope
| Control | Required contract |
|---|---|
| Authentication | Bearer access token. |
| Permission or scope | webhooks.manage capability and webhooks:write scope. |
| Resource scope | The endpoint is organization-scoped and optionally bound to an authorized project. |
Request fields
| Field | Type | Contract |
|---|---|---|
name | string | Required; 1–128 characters. |
url | URL | Required destination; private/internal destinations are rejected. |
events | string[] | Required canonical event types. |
description | string | Optional; up to 500 characters. |
retry_config | object | Optional validated delivery retry settings. |
signature_config | object | Optional HMAC header and tolerance settings. |
project_id | string | Optional authorized project. |
Code examples
import osfrom memorysync import ControlPlaneClientclient = ControlPlaneClient(base_url="https://api.memorysync.io",access_token=os.environ["MEMORYSYNC_ACCESS_TOKEN"],)webhook = client.create_webhook("Production events","https://hooks.example.com/memorysync",["memory.created"],project_id=os.environ["MEMORYSYNC_PROJECT_ID"],)
Response shape
{"id":51,"name":"Production events","url":"https://hooks.example.com/memorysync","secret_prefix":"whsec_abcd","events":["memory.created"],"enabled":true,"signature_algorithm":"hmac-sha256","project_id":"project_abc123","secret":"<shown-once>"}
- The raw
secretappears only on creation or explicit rotation. - Fetch
/org/webhooks/event-typeswhen your UI needs the canonical event list.
Status outcomes
Read the operation-specific response and persist only fields needed by the task.
Fix invalid path, query, or body fields before trying again.
Refresh authentication or verify the required organization permission and scope.
Treat the resource as unavailable without revealing whether it exists elsewhere.
Use returned retry metadata when present and reconcile uncertain mutations before repeating them.
Production handling
- 01
Authorize
APPConfirm the signed-in principal may perform this product action.
- 02
Validate
INPUTValidate identifiers and body fields before sending the request.
- 03
Call
SDKUse the named ControlPlaneClient method or equivalent HTTPS request from a trusted application context.
- 04
Inspect
RESULTStore the one-time secret immediately in an approved secret manager.
- 05
Reconcile
SAFEVerify the returned endpoint ID and project scope before reporting completion.
Security notes
Required
Keep organization controls inside trusted boundaries.
- Use an HTTPS destination you control.
- Never log or re-display the raw signing secret.
- Verify signatures and timestamps before processing webhook payloads.
Avoid
Do not weaken the route contract in client code.
- Do not expose bearer or refresh tokens in URLs, logs, or public clients.
- Do not accept organization, member, project, or resource IDs without application authorization.
- Do not treat returned data as trusted HTML, prompt instructions, or proof of application authorization.