Incoming webhook

An outside system posting an event to Era: address, token, duplicate protection and responses.

POSThttps://app.getera.io/api/webhooks/trigger/{path}

Endpoint token

An incoming webhook is how an outside system (a payment provider, a shop platform, your own software) tells Era "this happened". Every accepted call starts every workflow that listens for incoming webhooks.

Creating an endpoint

The Webhooks page

Open Settings → Advanced → Webhooks (/settings/webhooks) and click New endpoint.

Direction and path

Choose They call us as the Direction, then type a Name and a Path. The path may contain lowercase letters, numbers and hyphens, and is unique across Era. The address becomes https://app.getera.io/api/webhooks/trigger/<path>.

Store the token

When you click Register, the Endpoint token is shown once. Copy it and click I have stored it. Era keeps only a digest of the token.

The endpoint's detail shows its Address, the most recent body (Last payload) and the delivery history. When you rotate the token, the old one keeps working until the time shown on screen, so you can update the sender without downtime.

Authentication

Send the token in one of these headers:

Authorization: Bearer <token>
x-era-token: <token>

Request

Part	Description
Body	JSON. Anything that is not an object is wrapped as `{"value": ...}`. At most 256 KiB.
`Idempotency-Key` header	Optional. A second call with the same key is not processed again for seven days. `X-Idempotency-Key` is accepted too.

Example

curl -X POST https://app.getera.io/api/webhooks/trigger/demo-orders \
  -H "Authorization: Bearer WEBHOOK_TOKEN" \
  -H "Idempotency-Key: demo-order-001" \
  -H "Content-Type: application/json" \
  -d '{"orderReference": "demo-001", "total": 450}'

Responses

Status	Body	Meaning
`202`	`{"ok": true, "eventId": "1842"}`	Accepted; an event was created.
`200`	`{"ok": true, "duplicate": true}`	This `Idempotency-Key` was already processed.
`401`	`{"error": "Missing or wrong token. ..."}`	No token, or the wrong one.
`404`	—	No endpoint at this path.
`410`	`{"error": "This endpoint is switched off."}`	The endpoint is off.
`413`	`{"error": "Payload too large."}`	The body is over 256 KiB.
`429`	`{"error": "Too many requests. Slow down."}`	Rate limit reached.
`400`	`{"error": "Not accepted."}`	Refused for another reason.

202 means the event was received; it does not mean the workflows finished successfully. You see their results in the workflow's run history.

Limits

Each endpoint has a Requests per minute, per caller setting; the default is 60. The limit applies before the token check, so floods of wrong tokens are slowed down too. Callers are told apart by the IP address the request came from.