Register webhook
cooper_register_webhookUse this when the agent or app should be notified immediately (HTTP POST) when mail arrives instead of polling cooper_list_messages. Requires auth. Inputs: url (required; public http or https URL; localhost and private addresses are rejected), events (optional; any of message.received, message.held, message.sent, message.blocked, message.bounced, message.complained, task.received, owner.reply, domain.verified, draft.created, draft.approved, draft.rejected, draft.sent, account.sending_paused, account.sending_resumed, thread.assigned, thread.unassigned, thread.folder_updated, question.answered, question.expired; default [message.received]), inbox_id (optional; one inbox) or inbox_ids (optional; at most 10 inbox ids; omit both for every inbox), client_id (optional idempotency key; the same value returns the original hook with HTTP 200 and a redacted secret), headers (optional; up to 5 extra headers named Authorization or X-*, stored encrypted and never returned in full). Returns {id, url, events, inbox_id, inbox_ids, enabled, secret, headers (redacted), created_at}. Each delivery sends x-cooper-signature (sha256= HMAC of the raw body) and x-cooper-signature-v2 (v1= HMAC of timestamp, a dot, and the raw body) plus x-cooper-timestamp. message.blocked fires when an allow or block list drops inbound mail before it is stored. Fails with 400 too_many_inboxes, 400 invalid_url, or 404 inbox_not_found.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"url": "<url>"
},
"name": "cooper_register_webhook"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public https URL that receives POST deliveries | |
| events | No | Event types to deliver. Default: ["message.received"] | |
| headers | No | Up to 5 extra headers sent on delivery. Names must be Authorization or X-*. Values are stored encrypted and never returned in full. | |
| inbox_id | No | Only deliver events for this inbox. Stored into inbox_ids. Omit for every inbox on the account. | |
| client_id | No | Optional idempotency key. The same client_id returns the original hook with the secret redacted. | |
| inbox_ids | No | Up to 10 inbox ids. The hook matches when this list is empty or contains the event inbox. More than 10 returns 400 too_many_inboxes. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Stable id of the returned object. Pass it to the matching get, update, or delete tool. | |
| url | No | URL that receives POST deliveries. | |
| events | No | Event types this object delivers. | |
| secret | No | Signing secret. Shown in full once on create or rotate, redacted otherwise. | |
| enabled | No | True when the object is active. | |
| headers | No | Extra delivery headers. Values are redacted. | |
| inbox_id | No | Inbox id (inb_…) this object belongs to. Null when it applies to every inbox. | |
| client_id | No | Caller idempotency key stored with the object, or null. | |
| inbox_ids | No | Inbox ids this object is limited to. Empty means every inbox on the account. | |
| created_at | No | ISO-8601 time the object was created. | |
| disabled_at | No | ISO-8601 time Cooper disabled the hook, or null. | |
| disabled_reason | No | Why the hook was disabled, or null. | |
| consecutive_failures | No | Failed deliveries in a row. | |
| previous_secret_active | No | True while deliveries are also signed with the previous secret. | |
| previous_secret_expires_at | No | ISO-8601 time the previous secret stops signing, or null. |