Triggers and schedules
An agent fires on a repeating schedule, when a CRM record is created or a field changes, or on demand against records you select in a table. Each option has its own conditions and reprocessing rules.
Before you start
- You can set up background agents.
- A CRM is connected if you want to use CRM event triggers.
Step 1 of the agent form asks "What type of agent is this?". The answer decides what you configure next, what the agent runs against, and who pays for the run.
The trigger types
| Type | What it does | Runs against |
|---|---|---|
| Event-based | Runs when a CRM event happens | The one record that changed |
| Scheduled | Runs on a schedule (hourly, daily, weekly, or monthly) | Your book of records, or nothing but the prompt |
| Webhook | Runs when an external service sends data | The record identified in the payload, if you set one up |
| On-demand | Run manually from a table on selected records | The records you selected |
Switching between the schedule type and the others clears the record type, because it means something different in each.
Scheduled runs
Choose Repeats, then fill in what that repeat needs.
- hourly: pick the interval from Every hour up to Every 12 hours.
- daily: pick Every day, Every other day, or up to every 7 days.
- weekly: tick the weekdays under On these days.
- monthly: pick the date under On day. Days 1 to 28 are available, so a schedule never silently skips a short month.
Then set the time under At, in five-minute steps.
The agent list resolves this and shows the real Next run on every row, so check that after saving rather than trusting the picker.
A scheduled agent can also be pointed at a set of records to scan rather than run as a plain prompt. Under Which records should this agent process? pick the record type, add the conditions that select them, and set a cap on how many records one run may process. Leave it alone and the agent simply runs your instructions on the schedule.
A scheduled agent can also be pinned to a fixed list of records rather than a filter. That is how Key Account Monitoring works when you upload an account list during setup. The row then reads "for {n} attached Organization records" instead of showing filters.
Advanced: cron schedule
The schedule step carries a basic and advanced tab. Basic is the Repeats, Every, On these days and At pickers above. Advanced swaps them for a raw cron expression box, for the schedules the pickers cannot represent.
Type an expression such as 0 9 * * 1-5 and Spiich shows a plain-English preview underneath it, for example "At 09:00 AM, Monday through Friday", so you can check it reads the way you meant before you save. An expression that does not parse shows Invalid cron expression.
Cron schedules still run in the agent member's timezone, exactly like the basic pickers.
CRM event triggers
Event-based agents react to your CRM instead of the clock. Step 2 asks "When should this agent activate?".
Pick the record type
Organization, Person, Deal or Task. Note is available when the workspace is connected to HubSpot.
Pick the event
Created or Updated. Note agents only support Created, and can be narrowed to a source integration under "From which integration?".
Pick the field, for Updated
Under "Which field change should trigger this?", choose the exact field whose change starts the agent. Without this, every edit to the record fires it.
Add the conditions
Under "What conditions must be met?", click Add a rule and build a field, operator and value test, then set Match to
all rulesorany rule.
The operators depend on the field type:
| Field type | Operators |
|---|---|
| Text | is exactly, is not, contains, does not contain, starts with, ends with, is empty, is not empty |
| Number or currency | equals, does not equal, is greater than, is less than, is at least, is at most |
| Select or label | is exactly, is not, is one of, is not one of |
| Date | in the last, not in the last, is before, is after, is between |
| Multi-value | includes, does not include |
You can nest a group of rules inside a group. Adding another rule is blocked until the current one is complete.
Two CRM-specific gotchas: on Attio, Task plus Updated is switched back to Created automatically, and the Note record type exists only on HubSpot. See How CRM sync works.
Webhook trigger
A Webhook agent starts when an outside service posts JSON to a private URL Spiich generates for it. Here is the setup end to end.
Start a Custom Agent
Go to Background Agents, click Create new, then Custom Agent. In Step 1, "What type of agent is this?", click Webhook.
Generate the URL
In Step 2, "Webhook configuration", click Generate Webhook URL. Spiich creates the endpoint and shows it under Webhook URL, with a copy button.
Set the rate limit
Choose how many requests per second the endpoint accepts, from 1 request / second up to 5 requests / second (max), the maximum allowed per customer.
Point it at a record, if the payload identifies one
Fill in Record ID field (optional), the JSON property in the incoming body that holds the record identifier, then choose a Lookup mode: By CRM external ID or By attribute value (pick the Lookup attribute for the latter). Set this and the matching record reaches the agent as context. Leave it blank and the agent runs with no record context.
Add a description
Description (optional) notes which service calls this webhook, for whoever edits it next.
Copy the secret
Under Secret (save it now; it will not be shown again), copy the value and store it in the calling service. It is shown exactly once.
Sign every request with that secret so Spiich can trust it: compute an HMAC-SHA256 hex digest of the request body and send it in the X-Webhook-Signature header as sha256=<hex>.
Check what arrived under View logs, Delivery History, on the agent's webhook configuration. A fresh webhook reads "No deliveries yet."
Lost the secret, or think it leaked? Click Regenerate secret. The old one is invalidated immediately and any service still using it starts failing until you update it.
Running an agent on records you picked
Any agent set to On-demand can be fired from a table. An Event-based or Webhook agent joins them by switching on Allow running from Tables view, which adds manual runs on top of its automatic ones.
Select the records
Open Tables, open the table you want and select the records the agent should work on.
Open the Run agent menu
In the bulk action bar, click Run agent. Under Background agents you see the agents available for that record type, each with its credit price. An agent with no record type set appears on every table.
Confirm
The dialog gives the estimated credit cost and says "These runs are billed to you". Click Run agent.
A single record has the same menu on its header bar.
Stopping an agent from repeating work
Two settings at the bottom of the form are the difference between a useful agent and an expensive one.
Run once per record controls when a record the agent already processed successfully becomes eligible again: Once ever, once per calendar day, week, month or year, or a Custom interval of 1 to 999 days, weeks, months or years. Calendar windows use the agent member's timezone and a week starts Monday.
Daily run limit caps successful runs per day, counted in UTC. Leave it blank for no limit. Once the cap is reached, further attempts are refused with "Daily limit reached" and logged in Usage History. The agent is deliberately not paused, because you set the cap on purpose.
The agent's Records section shows the result: an Up next tab listing what the next run will pick up, and an Already run tab with each record's next opportunity.
Limits
- Monthly schedules can only use days 1 to 28, and hourly schedules repeat at most every hour.
- Daily run limits accept 1 to 10,000 successful runs per day.
- Event-based agents can only be run manually against organization, person and deal records.
- Attached record lists work on scheduled agents only.
- Webhook rate limit is 1 to 5 requests per second, the maximum allowed per customer.
- A webhook signing secret is shown once at creation. Regenerating it invalidates the old one immediately.
- A webhook agent needs Allow running from Tables view switched on before it can also be run manually.
If something goes wrong
The agent runs at the wrong time of day. The schedule uses the timezone of the member the agent runs as. Set that timezone in Settings > User Settings, or change the schedule time, then check the resolved Next run.
The agent keeps reprocessing the same records. No Run once per record policy is set, so a record stays eligible after every successful run. Open Configure, switch it on and pick a cadence, then confirm in Records > Already run.
Run agent now on an event-based agent asks for a record. That is expected. Event-based, webhook and on-demand agents work on one record at a time. Pick it in the search dialog, or run the agent from Tables against a selection.
The agent processed far fewer records than expected. The per-run record cap applies, trimmed further by whatever is left of the daily run limit. Raise the cap in Configure and check the limit is not throttling the fan-out.
I lost the webhook secret. Open the agent, go to Configure > Webhook configuration and click Regenerate secret, then update the calling service. The old secret stops working immediately.
The service calling my webhook gets 404 errors. The webhook was deleted, which stops the URL working immediately. Generate a new one from Configure > Webhook configuration and update the URL and secret in the calling service.