How to do it
- Mint a key for Zapier In https://app.socialhandoff.com, open Connections, add an agent called Zapier, and grant draft on the networks the Zap targets.
- Add a Webhooks by Zapier action After your trigger, add Webhooks by Zapier and choose the Custom Request event. It lets you send a raw JSON body with an array of networks.
- Fill in the request Method POST, URL https://app.socialhandoff.com/v1/posts, and in Headers add Authorization with the value Bearer and your key, plus Content-Type application/json.
- Write the body Paste the JSON below into Data and map fields from the trigger into body. Make sure mapped text does not break the JSON quotes.
- Test the step Run the test. A 201 response with a post id means the draft is in your inbox.
{
"body": "New in the store: PRODUCT_NAME. Details: PRODUCT_URL",
"networks": ["x", "linkedin", "mastodon"],
"mode": "submit",
"idempotencyKey": "zap-RECORD_ID"
}How the Zapier step works
Zapier does not run an agent here; it forwards data. The trigger supplies the facts, the Webhooks step sends them to POST /v1/posts, and SocialHandoff does the rest: guardrail checks, the approval inbox, scheduling, publishing, retries, and the audit log. Replace PRODUCT_NAME, PRODUCT_URL, and RECORD_ID in the snippet by inserting fields from your trigger in the Zap editor.
Webhooks by Zapier is a premium app, so it needs a paid Zapier plan.
Why Custom Request and not POST
The POST event builds form-style key-value data, which makes an array like "networks": ["x", "linkedin"] awkward. Custom Request sends the raw JSON exactly as written. If your mapped text may contain quotes or line breaks, add a Formatter step first to escape it, or the body will be invalid JSON and the API will return 400.
Modes
draftkeeps it as a private draft.submitsends it to the approval inbox, which is what most Zaps want.scheduleasks for a slot. Includedate,time, andtimezone, or ascheduledAttimestamp. Scheduling still waits for approval unless the Zapier agent has been promoted.
Zap ideas
- New Airtable record in a Ready view, then a submitted draft for LinkedIn.
- New Google Calendar event tagged webinar, then an event promo draft for X and Bluesky.
- New Stripe product, then a launch draft that a marketer reviews before it posts.
- Catch a SocialHandoff
post.publishedwebhook with Catch Hook and log it to a sheet.
Idempotency
Zapier can replay a step if you re-run a Zap. Put a stable id from the trigger in idempotencyKey. The same key returns the existing post rather than a copy.
Troubleshooting
- 400: invalid JSON, usually unescaped quotes from a mapped field.
- 401: missing header, or the value lacks the word Bearer.
- 422: a guardrail rejected the draft, such as over-length text for X.
- 423: the kill switch is on, so scheduling is paused.
Guides per network: Zapier for X, Zapier for LinkedIn, Zapier for Bluesky, Zapier for Mastodon, and Zapier for Threads.