Connecting Zapier, Make or a CRM

An outside service such as Zapier, Make or your CRM can tell a Benecaster add-on that something happened, by posting to one address on your site. A CRM that has just added a guest can tell your guest add-on so, for example. Benecaster checks every call before the add-on sees it: who is calling, that the add-on is active on the show, and that the data is what the action expects.

This is the other half of Outbound Webhooks, which send events out of your site. Both live on Benecaster → Settings → Webhooks: the actions are under Incoming actions, below the outbound settings.

---

Before You Start

It uses WordPress Application Passwords. There is no Benecaster key or token to copy. The service signs in as a WordPress user, with a password WordPress generates for that user.

Some security plugins and hosts switch Application Passwords off automatically. The sign is that there is no Application Passwords section on Users → Profile. To turn them back on, look in your security plugin’s settings for one named Application Passwords or Disable application passwords, or ask your host. When WordPress reports them unavailable, Settings → Webhooks → Incoming actions shows a yellow warning saying so.

WordPress offers them only over HTTPS (or on a local development site). A site served over plain http:// has no Application Passwords section at all.

Each Application Password acts as its user, so use a dedicated Benecaster Integration user, never an administrator’s account. An administrator’s password pasted into Zapier can do anything that administrator can. A user with the Benecaster Integration role can run integration actions and nothing else: in the WordPress admin it sees only the Dashboard and its own profile, it cannot open any Benecaster screen, and every Benecaster admin route answers it with 403.

---

Setting It Up

1. Go to Users → Add New (the Add a new user link under Incoming actions opens it). Create a user for the service, for example zapier, and set Role to Benecaster Integration. Click Add New User.
2. Go to Users → All Users, open that user, and scroll to Application Passwords. Type a name for the service (for example Zapier) and click Add New Application Password. WordPress shows the password once: copy it.
3. In the service, choose HTTP Basic authentication. The username is the user you created; the password is the Application Password (with or without its spaces).
4. Have the service send a POST to https://yoursite.com/wp-json/benecaster/v1/actions. The exact address for your site is shown under Incoming actions.

Actions available, under Incoming actions, lists every action your add-ons accept, grouped by add-on, with the fields each one expects, for example guest_id (integer, required), note (string). If it reads No add-on you run offers an action yet., none of your active add-ons accepts calls.

To disconnect a service, delete its Application Password on that user’s profile, or delete the user.

---

The Request

POST /wp-json/benecaster/v1/actions
Authorization: Basic base64(username:application-password)
Content-Type: application/json

{
  "action": "podcast-workflow.guest.crm_linked",
  "show_id": 12,
  "idempotency_key": "zap-8f2c41-guest-381",
  "data": { "guest_id": 381, "crm_id": "0031x00000ABCDe" }
}

Services such as Zapier and Make send most values as text, so text is accepted where it is unambiguous: "12" counts as the number 12 and "true" as true. A key in data that the action does not expect is ignored rather than refused.

A successful call answers 200:

{ "action": "podcast-workflow.guest.crm_linked", "show_id": 12, "call_id": 5521, "replayed": false, "result": { "guest_id": 381, "checklist_item": "crm" } }

result is whatever the add-on returned.

To see which actions the signed-in user can run right now, GET /wp-json/benecaster/v1/actions lists them, with their fields and the shows each can run on. Add ?show_id=12 to narrow it to one show.

---

When a Call Is Refused

The checks run in a fixed order, and a caller is never told whether an action exists before it has shown it may run actions.

The add-on itself can also refuse a call, with its own code and a 4xx status.

---

Repeated Calls

Zapier and Make retry a call when they do not hear back in time, so the same request can arrive twice. Send an idempotency_key to make that harmless.

• A repeat of the same request with the same key, within 24 hours, is not run again. It gets the first call’s answer, with "replayed": true and the header X-Benecaster-Idempotent-Replay: true.
• The same key with a different action, show or data is refused with 409 benecaster_idempotency_key_reused.
• Keys are kept per calling user, so two services using the same key do not collide. After 24 hours a key is forgotten and can be used again.
• A call refused before the add-on ran, for bad data for example, does not use up its key: fix the request and send it again with the same key. A 500 does not use it up either.

A call with no key is still accepted; it simply has no protection against being run twice.

---

Recent Calls

Incoming actions → Recent calls shows the last 50 calls, newest first: the action, the add-on, the show, Called by (the user the service signed in as), the Result (Done, Refused, Failed, or Repeat — first answer sent again) with its status and error code, and the time. Calls are kept for 30 days.

The data a service sent is never stored, so the log holds nothing about your listeners. A call that failed the sign-in or role check is not logged at all; one refused for any later reason is, because that is what you need to see when a Zap stops working.

Calls are not suppressed on a staging site: a staging copy receives only the calls someone points at it.