Overview
Webhooks let your server receive HTTP POST callbacks when events occur in SmartlyQ - a post publishing, a new comment or DM arriving, a contact being created, your wallet running low, and more. Events cover posting, accounts, inbox, reviews, jobs, billing, commerce, CRM and calendar.Setting up webhooks
Two ways to register an endpoint (both HTTPS-only, public URLs):- Dashboard: Developer Dashboard → Webhooks tab → add an endpoint URL and select events.
- API:
POST /webhookswithurland aneventsarray (see the API reference). The response includes the signingsecret- shown exactly once. A connected app (Zapier, Pabbly Connect, Make) gets no secret, and when it subscribes an address it already has, that webhook is updated instead of a second one being added.
GET /webhooks), create (POST /webhooks), update url/events or pause/resume (PUT /webhooks/{id}), send a signed test delivery (POST /webhooks/{id}/test), inspect the delivery log (GET /webhooks/logs), and delete (DELETE /webhooks/{id}).
Limits and safety: up to 10 active webhooks per workspace that you add yourself (dashboard or API key), plus up to 50 created by connected apps such as Zapier, Pabbly Connect and Make (one per Zap, workflow or scenario, removed by the app when the trigger is turned off); paused and failing webhooks do not count; URLs must be public HTTPS endpoints (internal/private addresses are rejected at save time and re-checked at delivery time); unknown event names are rejected with a validation error. Webhooks are a developer-workspace resource: the X-Profile-Id header is not accepted on webhook routes - profile events reach your webhooks automatically via fan-up.
Delivery envelope
Every delivery is JSON with the same envelope:idis a stable event identifier: it is shared across fan-out to multiple endpoints and reused on every retry of the same delivery, so you can deduplicate at-least-once delivery. It is also echoed in theX-SmartlyQ-Event-Idheader so you can dedupe without parsing the body.created_atis UTC, ISO 8601.datais the event-specific payload (catalog below).
Profiles fan-up: if you use Profiles (sub-accounts for your end customers), events raised inside a profile’s workspace are also delivered to your webhooks, with two extra fields added to
data: profile_id and profile_workspace_id, so you can attribute the event to the right end customer.Headers
Verifying signatures
X-SmartlyQ-Signature carries t=<timestamp>,v1=<hmac>, where <hmac> is the HMAC-SHA256 of <timestamp>.<raw-body> keyed with your webhook secret. The timestamp rotates on every attempt; the body (and id) stay the same.
Retry policy
- Non-2xx responses are retried up to 5 attempts with exponential backoff (the first at once, then ≈2, 4, 8 and 16 minutes later).
- If your endpoint answers
429with aRetry-Afterheader, we honor it (capped at 1 hour) instead of the standard backoff. - After the final attempt the delivery is marked dead-letter (it is not silently dropped - you can re-run it from the dashboard Logs).
- 10 consecutive failures flip the endpoint to
failingand pause deliveries until you fix and re-enable it. - A
410 Goneanswer is never retried: it means the receiver no longer wants the events. A webhook a connected app created is deleted; one you added is set tofailing. - Delivery records are retained for 90 days.
Event catalog
All registerable events. Registering an event name outside this catalog is rejected with a validation error.Posting
post.published, post.partial and post.failed describe the post’s overall state: platforms[] and results[] always cover the whole post.
- After a retry (from the API, the app’s Retry button or the automatic retry) one of them is sent again only when the post’s state changed, for example
post.failedand laterpost.published.retried[]then lists the platforms that were tried again. A retry that leaves the state as it was sends nothing, so a post that keeps failing does not run your workflow on every attempt. One exception: when the automatic retry gives up, a lastpost.failedorpost.partialis sent withwill_retry: false. will_retry(on all three events):truewhen the automatic retry will try the post again (at most 3 attempts, within 24 hours), so you can wait for the final outcome;falsewhen it will not, for example after 3 attempts or when every failure needs you to change something. Alwaysfalseonpost.published, so one filter “will_retry is false” catches every finished post.- They are also sent when a post fails as a whole outside a publish run, for example it was stuck mid-publish, or the social service is not enabled for the workspace.
- In webhooks,
results[].error.fixandresults[].error.docs_urlare alwaysnull;code,message,retryableanddetailare the same as on the API. API answers also fill infix;docs_urlis filled in only where an error reference page is published, so expectnull. - One post can produce more than one of these events: deduplicate on the envelope
id, not onpost_id.
Accounts
Inbox
Reviews
Jobs
Per-job webhook URL
POST /shorts/generate and POST /edits also take a webhook_url: a public HTTPS URL that gets this job’s job.completed or job.failed, even if you have no registered webhooks. The 202 response returns a webhook_secret for that job, shown once; verify X-SmartlyQ-Signature on those deliveries with it. Same envelope, retries and safety checks as registered webhooks. A Magic Shorts job whose clips all failed is reported as job.failed.
A video edit (POST /edits) sends job.completed twice: when it is ready (stage: "ready", open it with editor_url) and when an export finishes (stage: "exported", the MP4 at output_url). A failure sends job.failed with stage edit or export, error and error_code. Each is sent once per edit or export.
Billing & keys
Commerce
Payments your customers make to you: orders from your funnels, stores, payment links and invoices, form payments, and SaaS packages your clients buy; and invoices that are not paid by their due date.amount is in major units (e.g. 49.5). These events carry customer details, so a webhook created by a team member without access to payments, or limited to the contacts assigned to them, does not receive them.
CRM
CRM events fire regardless of whether the change came from the app or the API.Calendar
Booking events fire once per real change to a booking made through your event types - from the booking page, the app, the API or the calendar itself. A repeated update that changes nothing sends nothing.booking is {id, uid, status, title, description, start_time, end_time, timezone, location {type, meeting_url, address}, event_type {id, slug, title}, host {name, email, user_id}, guests[], no_show_guests[], topic, guest_notes, answers{}, is_recurring, rescheduled_from_uid, created_at}. start_time and end_time are UTC (ISO 8601); timezone is the guest’s. topic is the answer to the built-in question “What is this meeting about?”, guest_notes what the guest wrote in the form’s notes field, and answers the booker’s answers to the questions you added, keyed by question name. no_show_guests are the emails of the guests marked as not coming (lower-case, empty when nobody). Your team’s own booking notes are never included.
Booking events carry contact details, so they follow the same rule as CRM events: a webhook created by a team member without CRM access, or limited to the contacts assigned to them, does not receive them. Appointments copied in from a connected Google Calendar are not bookings and send no booking events.
Machine-readable payload schemas for every event ship in the OpenAPI spec under the standard OpenAPI 3.1
webhooks object, so SDK generators and AI agents can consume them.
