Trigger

​

Trigger types

​

Manual

​

Webhook

​

How signing connections work

• A scheme: one of Spojit, Shopify, GitHub, Slack, or Custom. The scheme determines which header carries the signature, what gets signed, and how it’s encoded.
• One or two signing secrets. Two enables zero-downtime rotation; both verify simultaneously during the rotation window.

​

Setup

1. Select the trigger node, set Trigger Type to Webhook.
2. Click + next to the Signing connection picker.
3. Pick a connector tile:
   • Spojit: we generate the secret. Pick this when you control both sides of the integration (your own backend, scripts, internal tools).
   • Shopify / GitHub / Slack: paste the signing secret from your provider’s app settings.
   • Custom: for any provider we don’t have a preset for; you configure header, encoding, algorithm, and payload shape.
4. Name the connection (e.g. “Shopify production”), provide the secret if applicable, and Create.
5. The connection is auto-selected. Copy the Webhook URL and paste it into your provider’s webhook configuration.

​

Choosing a scheme

​

Provider presets

​

Spojit

• Compute Unix timestamp in seconds
• HMAC-SHA256 of <timestamp>.<raw-body> using your secret
• Hex-encode the result
• Send as header: X-Spojit-Signature: t=<timestamp>,v1=<hex>
• Optional: X-Spojit-Event-Id: <unique-id> for deduplication.

​

Shopify

​

GitHub

​

Slack

​

Custom

​

Example: Postman

• Method: POST
• URL: your webhook URL (from the trigger properties panel)
• Headers:
  • Content-Type: application/json
  • X-Spojit-Signature: generated by the pre-request script below
  • X-Spojit-Event-Id: any unique string (optional; used for deduplication)
• Body (raw JSON):

{
  "event": "order.created",
  "data": {
    "orderId": "ORD-12345",
    "amount": 99.99
  }
}

const secret = "whsec_YOUR_SECRET_HERE";
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = pm.request.body.raw;
const payload = timestamp + "." + body;
const signature = CryptoJS.HmacSHA256(payload, secret)
  .toString(CryptoJS.enc.Hex);

pm.request.headers.upsert({
  key: "X-Spojit-Signature",
  value: "t=" + timestamp + ",v1=" + signature
});

​

Example: Node.js

import crypto from "node:crypto";

const secret = "whsec_YOUR_SECRET_HERE";
const body = JSON.stringify({ event: "order.created", data: { orderId: "ORD-12345" } });
const timestamp = Math.floor(Date.now() / 1000);
const signature = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${body}`)
  .digest("hex");

const response = await fetch("https://your-webhook-url", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Spojit-Signature": `t=${timestamp},v1=${signature}`,
    "X-Spojit-Event-Id": "evt_unique_123",
  },
  body,
});

console.log(response.status); // 202

​

Example: Python

import hmac, hashlib, time, json, requests

secret = "whsec_YOUR_SECRET_HERE"
body = json.dumps({"event": "order.created", "data": {"orderId": "ORD-12345"}})
timestamp = str(int(time.time()))
signature = hmac.new(
    secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256
).hexdigest()

response = requests.post(
    "https://your-webhook-url",
    headers={
        "Content-Type": "application/json",
        "X-Spojit-Signature": f"t={timestamp},v1={signature}",
        "X-Spojit-Event-Id": "evt_unique_456",
    },
    data=body,
)

print(response.status_code)  # 202

​

Response codes

​

Deduplication

​

Secret rotation

1. Click Rotate / add secret to create a second secret.
2. Spojit scheme: copy the newly generated secret (shown once). Other schemes: rotate the secret upstream (in Shopify / GitHub / Slack admin, etc.), then paste the new value here.
3. Both secrets verify simultaneously. Check the Last used timestamp on each; once the new secret shows recent activity, you’ve fully cut over.
4. Delete the old secret.

​

Webhook payload

​

Polling execution status

GET /api/executions/{executionId}/status

X-Spojit-Signature: t=<unix-timestamp>,v1=<hex-hmac-sha256>

{
  "executionId": "cc74c932-59a8-4838-aef7-744b7a53637f",
  "status": "RUNNING",
  "currentStep": {
    "id": "connector-abc123",
    "label": "AI Agent",
    "status": "RUNNING"
  },
  "stepsCompleted": 1,
  "totalSteps": 3,
  "output": null,
  "error": null
}

​

Example: Node.js polling

import crypto from "node:crypto";

const secret = "whsec_YOUR_SECRET";
const executionId = "cc74c932-59a8-4838-aef7-744b7a53637f";

async function pollStatus() {
  const timestamp = Math.floor(Date.now() / 1000);
  const signature = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${executionId}`)
    .digest("hex");

  const response = await fetch(
    `https://your-spojit-host/api/executions/${executionId}/status`,
    {
      headers: {
        "X-Spojit-Signature": `t=${timestamp},v1=${signature}`,
      },
    },
  );

  return response.json();
}

// Poll until terminal status
while (true) {
  const status = await pollStatus();
  console.log(status.status, status.currentStep?.label ?? "-");
  if (["COMPLETED", "FAILED", "CANCELLED"].includes(status.status)) {
    console.log("Output:", status.output);
    break;
  }
  await new Promise((r) => setTimeout(r, 2000));
}

​

Example: Python polling

import hmac, hashlib, time, requests

secret = "whsec_YOUR_SECRET"
execution_id = "cc74c932-59a8-4838-aef7-744b7a53637f"

def poll_status():
    timestamp = str(int(time.time()))
    signature = hmac.new(
        secret.encode(),
        f"{timestamp}.{execution_id}".encode(),
        hashlib.sha256,
    ).hexdigest()

    response = requests.get(
        f"https://your-spojit-host/api/executions/{execution_id}/status",
        headers={
            "X-Spojit-Signature": f"t={timestamp},v1={signature}",
        },
    )
    return response.json()

while True:
    status = poll_status()
    print(status["status"], (status.get("currentStep") or {}).get("label", "-"))
    if status["status"] in ("COMPLETED", "FAILED", "CANCELLED"):
        print("Output:", status["output"])
        break
    time.sleep(2)

​

Example: Postman

const secret = "whsec_YOUR_SECRET";
const url = pm.request.url.toString();
const match = url.match(/\/executions\/([^/]+)\/status/);
const executionId = match ? match[1] : "";

const timestamp = Math.floor(Date.now() / 1000).toString();
const payload = timestamp + "." + executionId;
const signature = CryptoJS.HmacSHA256(payload, secret)
  .toString(CryptoJS.enc.Hex);

pm.request.headers.upsert({
  key: "X-Spojit-Signature",
  value: "t=" + timestamp + ",v1=" + signature
});

​

Recommended polling cadence

• Start with 1–2 second intervals for short-running workflows
• Back off to 5–10 seconds for workflows that routinely take minutes
• Always stop polling once status is COMPLETED, FAILED, or CANCELLED; these are terminal

​

Schedule

​

Setup

1. Select the trigger node in the designer
2. Set Trigger Type to Schedule
3. Click Add Schedule
4. Edit the Cron expression (5-field Unix cron, e.g., 0 9 * * 1-5 for 9 AM weekdays)
5. Pick a Timezone (IANA, e.g. Australia/Sydney, America/New_York)
6. Leave Active on to have it fire; toggle off to pause
7. Click Save workflow; the schedule begins firing on the next matching time

​

Multiple schedules

• Business hours vs. weekends: one schedule for 0 9 * * 1-5 (weekdays 9 AM) and another for 0 12 * * 0,6 (weekends noon)
• Peaks and off-peaks: run every 15 minutes during business hours, every hour overnight
• Multi-region timing: one schedule in America/New_York, another in Europe/London, both hitting the same workflow

​

Cron format

┌───────────── minute (0-59)
│ ┌─────────── hour (0-23)
│ │ ┌───────── day of month (1-31)
│ │ │ ┌─────── month (1-12)
│ │ │ │ ┌───── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

​

Timezones

​

Pausing a schedule

​

Tips

• The Next fires preview shows the saved schedule, not your draft edits, so it’s a trustworthy readout of what’s actually going to run
• You can combine a Schedule trigger with a Manual or Webhook trigger on the same workflow. Each is an independent entrypoint that converges on the same downstream logic.
• Keep the cron on conservative intervals during development (e.g. every 10 min) to validate behavior before switching to production cadence

​

Email

​

How it works

​

Recommended pattern: dedicated mailbox

• Clear scope: Spojit only ever sees the dedicated mailbox, not your personal inbox
• Easy to revoke: disconnect the mailbox in Spojit or delete the mailbox in your workspace; either kills access
• Easy to audit: IT can see exactly what’s flowing through the dedicated address

​

Setup

1. Connect the mailbox in the Connections page:
   • Click Add connection → pick Gmail (trigger) or Outlook (trigger)
   • Choose a permission level:
     • Read only: Spojit can only read messages
     • Read + modify: Spojit can also mark messages as read or move them after processing (needed for the optional “After processing” actions below)
   • Sign in with the account that owns the mailbox
   • The connection appears in your list with the granted scopes visible
2. Add the trigger in the workflow designer:
   • Drop a Trigger node, set Trigger Type to Email
   • Click Add mailbox
   • Pick the connection from the dropdown
   • Pick the folder/label to watch (e.g., INBOX, or a custom label like Spojit/Orders)
   • Set the poll interval (1–60 minutes; default 2)
   • Optional: filter by sender domain or subject regex
   • Optional: pick what to do with the message after Spojit processes it
3. Click Save workflow; Spojit starts polling on the next cycle

​

Filters

• From allowlist: comma-separated patterns. @acme.com matches any sender at acme.com; orders@vendor.com matches the exact address. Multiple patterns are OR’d.
• Subject regex: a JavaScript-flavor regular expression. The message fires only if the subject matches.

​

After processing

• Mark as read: useful for visual confirmation that Spojit picked it up
• Move to label / folder: pick a destination; in Gmail the label is added (other labels stay), in Outlook the message moves out of the source folder

​

Multiple mailboxes per workflow

​

Multiple workflows watching the same mailbox

• No “first one wins”: each workflow gets its own copy of the email, runs its own logic
• After processing actions don’t hide messages from siblings: even if Workflow A moves the message to a Processed folder, Workflow B still sees and processes it within the same poll cycle. You won’t miss a workflow because of another workflow’s cleanup action.
• Conflicting after-processing actions apply in order: if A says “mark read” and B says “move to folder X”, both happen. In Gmail, labels accumulate; in Outlook, the move wins.

​

What Spojit can and can’t see

• Can see: messages in the folder you select. Spojit’s code is committed to only querying that folder, even though the OAuth scope technically grants whole-mailbox access (this is how Google/Microsoft OAuth scopes work; folder-level scoping isn’t an option from the provider).
• Can’t do (read-only connections): mark messages as read, move messages, delete messages
• Can do with Read + modify (only if you picked it at connection setup): mark as read, move/label, but never delete
• Doesn’t store: full message bodies. Bodies and attachments are passed into the workflow execution and retained per the workflow execution’s normal retention policy. They are not stored in any separate Spojit-owned mailbox.

​

Disconnecting

• Google: myaccount.google.com/permissions → find Spojit → Remove access
• Microsoft: myaccount.microsoft.com/consent → find Spojit → Remove

​

Tips

• Start with a dedicated mailbox: much easier story for IT and for limiting blast radius
• Use Read only by default; only upgrade to Read + modify if you actually want Spojit to mark or move messages
• The poll interval doesn’t need to be aggressive; 2–5 minutes is fine for almost every order-processing use case; 1-minute polls aren’t dramatically faster end-to-end given queue + provider latency
• Pair a dedicated mailbox with a forwarding rule from your main inbox to filter just the messages you want Spojit to act on
• For testing, send yourself an email matching your filters and watch the Recent activity panel to confirm it landed

​

Mailhook

​

Output

• Manual: The input data passed when clicking Run (if any)
• Webhook: The parsed HTTP request body
• Schedule: { scheduledAt }, the ISO-8601 timestamp of the firing that started the run
• Email: { from, to, cc, subject, textBody, htmlBody, headers, receivedAt, conversationId, attachments[] }. Each attachment is a reference ({ provider, providerMessageId, attachmentId, filename, mimeType, size }); the bytes are fetched on demand by downstream nodes that need them.
• Mailhook: { from, to, cc, replyTo, subject, text, html, truncated, receivedAt, emailId, messageId, attachments[] }. Each attachment is a reference ({ id, filename, contentType }); the bytes are fetched on demand by downstream nodes that need them. See Mailhook Trigger for the full shape.

​

Tips

• Start with Manual triggers during development, then switch to Webhook, Schedule, Email, or Mailhook when you’re ready for production
• A workflow can have multiple triggers (e.g., Manual + Webhook, or Schedule + Email); each is an independent entrypoint
• Use the Active toggle to temporarily pause any trigger without deleting it or losing the configuration