Email Studio

Incoming Webhooks

Add or unsubscribe readers automatically from Zapier, Make, n8n or any other tool that can send a web request.

What it does

An incoming webhook is a private link. Your automation tool sends it a reader's details, and StorytellerOS adds them to one pen name's audience with the tags, lists and fields you send. You decide in your tool which of your data goes into which of our fields, so it works with wherever your readers sign up.

  • Each webhook belongs to one pen name. Make as many as you like.
  • Readers who unsubscribed, or whose address could not receive email, are never added back.
  • Sending the same reader twice is safe. They are updated, never duplicated.
  • Empty fields never erase what you already have.
  • You can see what happened to every reader sent in the last 30 days.

Step 1: Create the webhook

  1. Go to Email Studio → Incoming Webhooks and pick the pen name at the top.
  2. Click New webhook and give it a name, such as “New signups from my website”.
  3. Optional: choose lists to add everyone to and tags to give everyone.
  4. Leave Ask new subscribers to confirm by email off if readers already confirmed where they signed up. Turn it on if they did not, and we send our own confirmation email first.
  5. Leave Start list and tag automations off if readers already get a welcome email from somewhere else, so nobody is emailed twice. Turn it on when StorytellerOS sends your welcome series.
  6. Click Create webhook, then Copy the link.

Copy the link right away

For your security we show the link only once. Anyone who has it can add readers to your pen name, so keep it private. If you lose it, or think someone else has it, click New link. The old link stops working at once, so paste the new one into your tool.

Step 2: The fields you can send

Only the email is required. Field names are not case sensitive, and firstName works as well as first_name.

  • email (required): the reader's email address.
  • first_name and last_name.
  • tags: tag names or tag ids, as a list or separated by commas. In a list, each item is used as it is, even if it has a comma in it. A name that doesn't exist yet on this pen name becomes a new tag. An id must belong to this pen name, or it is skipped.
  • lists: list names or list ids, the same way as tags.
  • fields: your own custom fields, as { "field key": value }. Use the keys you set up under Email Studio → Fields; inside fields, a field's name works too. You can also send a field key on its own, next to email. Values must fit the field's type (a number for a number field, and so on).
  • action: subscribe (the default, so you can leave it out) or unsubscribe.
  • event_id: optional. Your tool's id for this signup. If your tool sends the same event id with the same details again, we use the first result instead of doing the work again. If the details are different, for example an unsubscribe, we treat it as a new request.

Send it as JSON, or as form fields. Here is a full example:

{
  "email": "[email protected]",
  "first_name": "Rita",
  "last_name": "Reader",
  "tags": ["VIP", "ARC Team"],
  "lists": ["Main newsletter"],
  "fields": { "favorite_genre": "Cozy mystery" },
  "event_id": "signup-12345"
}

Note

Anything we can't use, such as a field key you haven't set up, is skipped and listed under Recent, so you can fix your mapping.

Step 3: Set up your tool

Any tool that can send a web request works. These are the steps in three common ones.

Zapier

  1. Create a Zap with the trigger you want, for example a new signup in your form tool.
  2. Add the action Webhooks by Zapier and choose POST.
  3. Paste your webhook link as the URL and set the payload type to json.
  4. Under Data, add email and pick the reader's email from your trigger. Add first_name, tags, lists and anything else you want from the list above.
  5. Click Test step, then publish the Zap.

Make

  1. In your scenario, add the module HTTP, then Make a request.
  2. Paste your webhook link as the URL and set the method to POST.
  3. Set the body type to Raw and the content type to JSON (application/json).
  4. In the request content, write the fields like the example above, mapping your data into each value.
  5. Run the scenario once to test it.

n8n

  1. Add an HTTP Request node after your trigger.
  2. Set the method to POST and paste your webhook link as the URL.
  3. Turn on Send Body, choose JSON, and add the fields from the list above.
  4. Run the node to test it.

Check that it worked

Back in Incoming Webhooks, click Recent next to your webhook. Each reader your tool sent is listed with what happened: added, updated, waiting to confirm, unsubscribed, or not added because they unsubscribed earlier. Anything that was skipped is listed with the reason.

Unsubscribes

To unsubscribe someone, send their email with action set to unsubscribe. They are unsubscribed from this pen name and won't be emailed. A reader who unsubscribed stays unsubscribed even if your tool sends them again later. If they really do want back in, they can sign up again on one of your StorytellerOS signup forms.

Turning a webhook off

Click Turn off to stop a webhook from accepting readers. Nobody already added is removed. Click Turn on to start it again with the same link.