Integrations, API and webhooks

Orquiva connects with 12 tools: Slack, Microsoft Teams, Discord, Google Workspace, Outlook Calendar, iCalendar feeds, single sign-on (SSO), the public API, outbound webhooks, n8n, Zapier and Make. There are no integrations with ERP or payroll software.

Integrations

Before you start

The catalog is under Integrations in the menu. Each integration also has its own page in the Integrations group of Organization. They’re set up by the administrator or by anyone with the permission for that integration.

In Organization, Slack, Teams, Google Workspace and Outlook Calendar may show the Pro badge. The public API is an add-on bought separately on any plan: without it, its page won’t open. Check it in Billing, plan and modules.

The catalog

At the top you pick the view: Marketplace (all of them) or My integrations (the connected ones). See all opens the full list, with a search box and the Category filter: Communication, Productivity, Calendar, Security and Development.

Each card reads Connect, Connected or Failing. Failing means it’s connected but the last check didn’t work (a revoked Google permission, for example).

Integration	What it does
Slack	With the app (Connect to Slack) it sends alerts to the Default channel and lets people approve or reject time off from the message. The Webhook (legacy mode) only sends alerts, with no buttons or commands.
Microsoft Teams and Discord	You paste the channel's Webhook URL and enable the integration. They only receive alerts.
Google Workspace	Connect to Google links an account. It lets you Export employees to Sheets and View upcoming events. In Drive it only touches files Orquiva creates.
Outlook Calendar	Connect Outlook sends the team's approved time off to a calendar. Sync now forces a sync.
iCalendar	Each person gets their ICS feed from their Preferences and subscribes to it in their calendar.
SSO	Google, Microsoft and other OIDC providers (Okta, Entra ID, Keycloak). There's no SAML. It's set up in Organization › Security.
n8n, Zapier and Make	These are guides: they connect through outbound webhooks and the public API.

In Slack, Teams and Discord, Send test confirms the message arrives. Which alerts reach the chat: Slack and Teams alerts. SSO is covered in Security. For n8n, Zapier and Make, follow Connecting n8n, Zapier or Make.

Setting up an outbound webhook

Open Outbound webhooks.
Under Endpoints, choose the Event type (or every event).
Type the Target URL and a Signing secret of at least 8 characters.
Click Add endpoint and store the secret: it isn’t shown again.
Click Test to queue a test event.

The events are: time off requested, approved, rejected, changed and canceled; employee created, edited and deleted; clock-in recorded, changed and deleted; and onboarding task completed.

Each delivery is a JSON POST with these headers: X-Orquiva-Signature (v1= followed by the hex HMAC-SHA256 of timestamp.eventId.body, signed with your secret), X-Orquiva-Timestamp, X-Orquiva-Event-Id and X-Orquiva-Event-Type. If the secret leaks, use Rotate secret.

Watching deliveries

Orquiva makes up to 5 attempts, waiting 1 minute, 5 minutes, 15 minutes and 1 hour in between.

Status	What it means	What you can do
Queued	Not sent yet.	Wait.
Sending	The delivery is in progress.	Wait.
Retrying	It failed and will be tried again.	Fix your endpoint in the meantime.
Delivered	Your endpoint accepted it.	Nothing.
Failed	It ran out of attempts. It shows under Failed deliveries.	Click Retry once the endpoint works.

In Recent deliveries, click an event to see each attempt with its HTTP code and error.

Creating a public API key

In Public API, click Create API key.
Give it a name and check the minimum Permissions it needs.
If you want, add an Expiration date (optional) and Allowed IPs (optional), which accept CIDR ranges.
Copy the key before you close the window.

The key is shown once

You can’t see it again afterwards. If you lose it, click Rotate: a new key is generated and the old one stops working immediately.

A new key starts as Pending approval and doesn’t work until an administrator clicks Approve. After that it can be Active, Revoked or Expired.

Plan	Keys	Requests per minute
Starter	3	60
Professional	10	300
Enterprise	100	1,000

Connecting n8n, Zapier or Make

Orquiva has no dedicated connector for any of the three. Their catalog pages are guides with two buttons, Manage webhooks and Manage API keys, which lead to the two pieces they connect through. You can use either one or both.

Piece	What it's for	What you need
Outbound webhooks	Something that happens in Orquiva starts your workflow.	Nothing else: they're on every plan.
Public API	Your workflow reads or changes data in Orquiva.	The public API add-on, bought separately on any plan.

Your n8n, Zapier or Make account is your own and is paid for separately, on its own terms.

Receiving events in your workflow

In your tool, create the trigger that gives you a URL: in n8n, a “Webhook” node; in Zapier, “Webhooks by Zapier” › “Catch Hook”; in Make, “Webhooks” › “Custom webhook”. Copy the URL.
In Orquiva, open Outbound webhooks and, under Endpoints, choose the Event type.
Paste the URL into Target URL, type a Signing secret and click Add endpoint. Store the secret in your workflow: it isn’t shown again.
Click Test to check it arrives. For your tool to learn the shape of a real event, trigger one in Orquiva, such as a test time-off request.

Each delivery is a POST whose body is the event’s JSON; the type and ID travel in the headers. Keep in mind:

Each endpoint receives one event type or Every event. For several specific ones, create one endpoint per event with the same URL.
With Every event you also get clock-ins: one delivery for each one recorded, changed or deleted.
The URL has to start with https:// and be reachable from the internet. Orquiva doesn’t send to private or local addresses, so an n8n installed on your network without a public address receives nothing.
Your workflow has to answer with a 2xx code within 8 seconds. Otherwise the delivery counts as failed and is retried, as explained in Watching deliveries.

Checking the signature

Each delivery carries these headers:

Header	What it holds
`X-Orquiva-Signature`	`v1=` followed by the signature, in hex.
`X-Orquiva-Timestamp`	When it was sent, in Unix seconds.
`X-Orquiva-Event-Id`	The event's ID. It repeats on retries.
`X-Orquiva-Event-Type`	The event type.
`X-Orquiva-Tenant-Id`	Your company's ID in Orquiva.

To check that a delivery comes from Orquiva, add a code step to your workflow that does this:

Take the body exactly as it arrives, without reformatting the JSON.
Join the timestamp, the event ID and the body with dots: timestamp.eventId.body.
Compute the HMAC-SHA256 of that text with your secret, in hex.
Compare it with what comes after v1=. If it doesn’t match, discard the delivery.

const crypto = require("crypto");
const base = `${timestamp}.${eventId}.${rawBody}`;
const expected = crypto.createHmac("sha256", secret).update(base).digest("hex");
const valid = signature === `v1=${expected}`;

Also discard deliveries whose timestamp is more than a few minutes old, and use X-Orquiva-Event-Id so you don’t process the same event twice when a retry arrives. If you click Rotate secret, change the secret in your workflow too.

Calling the public API from your workflow

Create a key with the minimum Permissions, as explained in Creating a public API key, and ask an administrator to approve it.
In your tool, add an HTTP request: in n8n, “HTTP Request”; in Zapier, “Webhooks by Zapier” › “Custom Request”; in Make, “HTTP” › “Make a request”.
Add the X-Api-Key header with your key.
Use the same address you sign in to Orquiva with, followed by /public-api/v1/.

The header is X-Api-Key

The n8n, Zapier and Make guides inside Orquiva say to use the Authorization: Bearer header. With it, the API answers 401. Use X-Api-Key.

To test the key, request GET /public-api/v1/ping: it needs no permission and returns "status": "ok". A real example, with the Read employees permission: GET /public-api/v1/employees?is_active=true&size=100 returns the active people. Lists come back in data, with paging in meta (page, size, total_items, total_pages); pages start at 0 and hold up to 100 items. The full specification, in OpenAPI format, is at /v3/api-docs/public-api on that same address.

If something fails, the code tells you why: 401 if the key is missing, doesn’t exist, isn’t approved, is revoked or expired, or your company no longer has the add-on; 403 if the request comes from an IP that isn’t allowed or the key lacks the permission; 402 if your company’s subscription isn’t active; and 429 if you go over the per-minute limit (wait 60 seconds).

What happens next

An integration doesn’t change who sees what: permissions stay Orquiva’s. Webhooks start sending as soon as the first event of the chosen type happens.

If something goes wrong

I can’t approve time off from Teams or Discord. They only receive alerts. To decide from the chat you need Slack with the app installed.

The buttons or /orquiva whoisout don’t work in Slack. You’re on legacy mode. Install the app with Connect to Slack.

A card says Failing. The connection broke, almost always because a permission was revoked in the other tool. Open the integration, disconnect it and connect again.

My API key returns 401 or 403. Check whether it’s still Pending approval, whether it’s revoked or expired, whether the request comes from an IP outside the list, and whether its permissions cover what you’re asking for.

My deliveries end up as Failed. Your endpoint returned an error or didn’t respond. Look at the attempts, fix the endpoint and click Retry.

I don’t see Public API. You need the public API add-on. Check it in Billing, plan and modules.