mercury_create_webhook
Register a webhook to receive real-time Mercury events (e.g., invoice.paid, transaction.posted) via HTTPS POST. Enables external systems to react without polling.
Instructions
Register a new webhook endpoint. Mercury will POST events as JSON to the provided URL.
USE WHEN: subscribing an external system to Mercury events (transaction.posted, invoice.paid, etc.) so you can react in near real-time without polling.
DO NOT USE: with non-HTTPS URLs, loopback / RFC 1918 / link-local / cloud-metadata IPs — the MCP enforces a defense-in-depth gate on top of Mercury's own validation to block accidental SSRF or exfiltration via prompt injection.
SIDE EFFECTS: writes a new webhook subscription to Mercury. Persistent. Once registered, Mercury immediately starts delivering matching events to your URL — make sure the endpoint is ready to receive (and ideally verify Mercury's signature). NOT idempotent at the API level — calling twice creates two subscriptions firing duplicate events.
RETURNS: { id, url, status, events, ... } — keep id for mercury_update_webhook / mercury_delete_webhook.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Publicly reachable HTTPS URL that will receive webhook events (POST). Must not be a loopback, private, or link-local address. | |
| events | Yes | Event types to subscribe to. Common values: - transaction.created / transaction.updated - transaction.posted / transaction.pending / transaction.failed - invoice.created / invoice.sent / invoice.paid / invoice.overdue / invoice.cancelled - customer.created / customer.updated - recipient.created / recipient.updated Check https://docs.mercury.com/reference/webhooks for the full list. |