API keys, webhooks and WordPress

Everything ErmisAI offers for wiring itself into other systems sits on one screen: Settings → Integrations, headed Integrations with the subheading API keys, webhook status, and delivery observability. This page is about operating that screen. For which delivery routes exist and what each one carries, read Getting approved stories out first.

Who can open Integrations

Only the workspace owner. There is no read-only mode: admins and members do not see the section in the settings navigation at all, and every action behind it is refused for them.

The section also has to be unlocked by your plan. On Free it is absent from settings entirely. And if ErmisAI cannot read your billing data at that moment, the section disappears and settings shows Billing access check failed with Billing data is temporarily unavailable. Team and integration entitlements could not be resolved. That is a temporary condition, not a downgrade — reload once billing recovers.

What each plan unlocks

The three capabilities on this screen are gated separately.

Two consequences worth planning around.

On Plus, the API keys card is a trap. The card is on screen, but pressing Create key or Revoke fails with API keys require Pro or Enterprise, shown inside the API keys card and as a toast. Pressing Refresh is worse: the whole screen fails on that one refusal, so the webhook panels stop refreshing too, even though webhooks are included on Plus. Nothing is broken; you are simply a tier below API keys.

A lapsed payment blocks everything here, without hiding it. The settings screen decides what to show from your plan alone, while every action checks your plan and your payment standing. A past-due Pro workspace still sees the API keys and WordPress cards, and every button behind them is refused until the invoice is settled. See Billing and AI capacity.

API keys

A key gives an outside system read access to your approved stories. It authenticates requests coming in to ErmisAI — it is not used for anything ErmisAI sends out. Keys belong to the whole workspace, not to the person who created them.

The card is headed API keys with the subheading Create tenant-scoped keys for CMS sync and external consumers.

Creating one

A key looks like ermis_ followed by 48 hexadecimal characters. ErmisAI stores only a one-way hash of it, so there is no way for anyone — including support — to recover a lost key. Create a replacement and revoke the old one.

The key list

Each row shows the label, a masked value (ermis_, eight bullets, then the last four characters), a Revoke button, and a line reading Created date · Last used date, or never if nothing has used it yet. When there are no keys the card reads No API keys available.

Last used is the only usage signal on this screen. If a key that should be polling shows never, the consumer never authenticated successfully.

Revoking

Revoke takes effect immediately and cannot be undone. There is no rotate action — replacing a key means creating a new one, updating the consumer, then revoking the old one, in that order.

Webhooks

The card is headed Webhook configuration with the subheading Configure endpoint, secret, and delivery status. It has exactly three controls — there is no event picker, no per-event subscription, and no choice of payload format.

Below them: Save configuration and Send test webhook, then a Last updated timestamp.

Setting one up

What actually gets sent

Two things, and only two: the manual test, and an alert when one of your monitoring rules matches a story. Nothing is sent when a story is composed, submitted, approved, rejected, or delivered. If you want to hear about a specific kind of story, you build a monitoring rule for it — see Alert rules and notifications.

The alert payload identifies the rule that fired and describes the story: its headline, category, confidence score, breaking and sensitive flags, source count, and source names. It does not contain the article body.

What your endpoint has to satisfy

• Public HTTPS. Internal hostnames, loopback addresses, private ranges, and any hostname that resolves to one of those are rejected outright. Split-horizon DNS and some enterprise or CDN setups will not pass.
• It must answer within ten seconds. Longer than that is recorded as a failure.
• It has to be reachable at the moment of delivery, not at the moment of saving. The address is only fully checked when a delivery is attempted, so a configuration can save cleanly and then fail on every send.

Send test webhook cannot be driven from a script — it is protected against automated traffic and only works from the browser. That makes it a check you run by hand after a change, not something you can put in a monitor.

Recent webhook deliveries

The table below the form shows the last attempts for the workspace, newest first: the endpoint, a status of success or failed, the HTTP code, and the timestamp. Empty state: No webhook deliveries recorded yet. It holds 120 rows, so it is a recent-activity view rather than a permanent record.

No payload is stored, and there is no re-send button. ErmisAI has no retry queue, no backoff, and no dead-letter list. A failed alert delivery gets another chance on the next monitoring evaluation; a failed test never does.

WordPress

Two things follow from how the connector works, each stated in ErmisAI's own copy:

• ErmisAI never pushes into WordPress. The connector pulls approved stories and creates or updates posts on the WordPress side. There is no Publish to WordPress button, no category mapping, and no control over post status here. The Connect WordPress approval screen states this: "ErmisAI will not publish into WordPress by itself…".
• The handshake starts in WordPress, not in ErmisAI. The WordPress connections card in Settings → Integrations says so: Install the ErmisAI Newsroom Connector in WordPress, then start the connection from Settings -> ErmisAI Newsroom.

Approving a site

The one-time code the connector exchanges is valid for 15 minutes and works once. If the connector fails to complete the exchange, start again from WordPress rather than reloading the approval screen.

If the plan does not allow it, the approval screen refuses with WordPress sync is not enabled on this plan and WordPress sync is available on Pro, Business Pro, and Enterprise plans., with an Open billing link. Inside settings the whole card is replaced by WordPress delivery is unavailable and This workspace plan does not include managed WordPress connections.

The connections card

Approved sites appear under WordPress connections, subheading Connected WordPress sites are managed as tenant-level integrations. Each row shows the site name (or the URL when there is no name), the URL itself, then Workspace, Key, Connected, Last activity (never until the connector first pulls), and the connector and WordPress versions it reported. The only control is Revoke access. Empty state: No WordPress sites connected yet.

Last activity is how you tell whether the connector is actually running. A site connected days ago that still reads never has not made a single successful request.

Revoking and reconnecting

Revoke access cuts the site off immediately and revokes its key at the same time. The reverse is also true, which is the part that catches people out: revoking that key from the API keys card deletes the connection.

Reconnecting a site you have already connected is safe and is the intended way to replace credentials. The card states it: Reconnecting the same site replaces the previous managed key automatically instead of leaving stale WordPress credentials behind. The old key stops working the moment the new connection is made, with no notification, so do not reconnect a site while another system is using that same key.

What to hand your developer

The person writing the receiving code needs three things from you: the API key (once), the signing secret you chose, and the pages below. Everything else they need is in them.

• Webhook requests carry a X-Ermis-Signature header in the form sha256=<hex>. The signature is an HMAC-SHA256 over the X-Ermis-Timestamp value, a full stop, and the raw request body — not the body alone. A receiver that verifies the body on its own will reject every delivery.
• Each delivery also carries X-Ermis-Event naming the event type and X-Ermis-Delivery-Id, which is stable per delivery and is what a receiver should use to discard duplicates.
• Only two event types exist: webhook.test and alert.triggered.

Outbound webhooks has the full signature scheme and both payloads. Public integration API has the story-export request and response contracts and the rate limits. WordPress connector handshake has the connect flow in full, for anyone building the connector itself.

When something is refused

The three plan-gate messages come back from the server in English regardless of your interface language. The rest are produced by the form itself and appear in your interface language.