Webhooks

A webhook is an address Marcora can send data to when you ask, from a conversation or a workflow. Use one to reach a tool that isn't in Connected Apps, such as your CMS, an automation platform or an internal system.

Before You Start

  • Find it under Integrations > Webhooks.
  • You need the https:// URL of the endpoint that will receive the data.
  • You need the Admin or Creator role. Collaborators see Creator License Required.
  • Your webhooks are private to you. Teammates and Admins don't see them.

Add a Webhook

  1. Open Integrations, then select the Webhooks tab.
  2. Select + Add Webhook.
  3. Enter a Name, and optionally a Description.
  4. Enter the URL. It must start with https://.
  5. Under Signing secret, choose Auto-generate, I'll provide my own or None.
  6. Optional: open the advanced custom headers section and select Add header for each header your endpoint needs.
  7. Select Add webhook.

With Auto-generate, Copy your signing secret appears. This is the only time you'll see it. Copy it into your receiver's settings, then confirm you've copied it to close the window.

You can also ask Marcora to set a webhook up for you.

Send a Test

  1. Select the three-dot menu on the webhook's row.
  2. Select Send test.

A message shows your endpoint's response, or why the test failed. The test request carries a small sample body.

Use a Webhook

Ask Marcora, in a conversation or in a workflow, to send something to the webhook by name. For example: "Send this draft to my CMS webhook." Marcora builds the request body for you.

How It Works

  • Marcora sends a POST request with a JSON body. Nothing is sent automatically when something changes in Marcora: only when you or a workflow ask.
  • With a signing secret, each request carries an X-Marcora-Signature-256 header (sha256= followed by the HMAC-SHA256 of the request body), plus X-Marcora-Webhook-ID and X-Marcora-Timestamp. Use the secret to verify the request came from Marcora.
  • Each request is tried once, with no retries. Redirects aren't followed, and private or local addresses are blocked.
  • A request body can be up to 100 KB. You can send up to 60 requests a minute, tests included.
  • Secrets and custom headers are encrypted and never shown again. To issue a new secret, select Rotate secret, then Save changes in the dialog that opens.
  • View logs for this webhook shows each request and its result. Delete removes the webhook but keeps its history.

Troubleshooting

"url validation failed" when you save. The URL points to a private or local address. Use a public https:// endpoint. If the logs show Target URL blocked (SSRF), the address resolved to a private network when Marcora sent the request.

"Rate limit exceeded." You sent more than 60 requests in a minute. Wait a minute and try again.

"Payload too large." The request body was over 100 KB. Ask Marcora to send less, such as a link instead of the full document.

"Connection failed." Your endpoint didn't respond. Check that it's running and reachable from the internet, then select Send test.