Guides & Tutorials9 min read

Build a Notion to LinkedIn Pipeline: A Social Media Automation Guide

By ButterGrow Team

TL;DR

This tutorial walks you through building a Notion to LinkedIn publishing pipeline with OpenClaw. You will query a Notion database, transform content, pass an approval gate, and publish via the LinkedIn UGC Posts API. We focus on reliability with idempotency, rate limiting, and observability. You will also see how to schedule posts safely, handle media uploads, and capture audit trails for approvals. The result is a repeatable system for social media automation that keeps your calendar on schedule without manual copy and paste.

Why build this pipeline

Marketing teams often maintain editorial calendars in Notion while publishing manually into LinkedIn. Manual work increases error rates, creates timing drift, and makes audits painful. A pipeline powered by AI agents can pull approved entries, apply guardrails, and post consistently. You get predictable delivery, fewer outages, and a clear record of who approved what.

Linking this tutorial to product context: if you want a quick look at what ButterGrow does at a high level, see the AI marketing automation features on the feature set. For a sense of how teams have approached content scheduling before, check out our developer story on building a content calendar bot with OpenClaw. When questions come up about onboarding or credentials, you can browse answers to common questions.

Architecture overview

  • Source of truth: a Notion database that holds post content and metadata.
  • Orchestrator: an OpenClaw playbook that ingests, filters, approves, and publishes.
  • Destination: LinkedIn UGC Posts API for organic posts, with optional image upload.
  • Guardrails: approval gate, rate limiter, retries, and idempotency keys.
  • Observability: logs, metrics, and alerts for failed runs and slow approvals.

The flow is simple. A scheduler queries Notion, selects rows marked Ready whose Publish Date is due, posts an approval task, then publishes to LinkedIn. Errors are retried intelligently, and duplicate posts are prevented with a content fingerprint.

Prerequisites

  • Notion workspace with a database for your calendar.
  • LinkedIn Developer account with an app that has access to UGC Posts for your organization or member.
  • OpenClaw workspace configured with a runner and secrets.
  • A company page URN or member URN for the author field in LinkedIn.
  • Optional: a Slack channel for approvals and incident notifications.

Data model and mapping

Create a Notion database with these properties and map them to LinkedIn fields.

Notion property Type Example LinkedIn field
Title Title Weekly Product Tip specificContent.shareContent
Body Rich text Short post body specificContent.shareContent
Image URL URL https://example.com/image.jpg Asset upload reference
Publish Date Date 2026-11-19T14:00:00Z Schedule trigger
Channel Select LinkedIn Pipeline filter
Status Select Ready, Draft, Paused Pipeline filter

Use Channel and Status to gate what is pulled. Keep drafts separate from Ready to avoid accidental posts.

Credentials and environment

You will need OAuth credentials for LinkedIn and a Notion API token. Store them in OpenClaw secrets, not in plaintext. The minimum set:

  • NOTION_TOKEN
  • NOTION_DATABASE_ID
  • LINKEDIN_CLIENT_ID
  • LINKEDIN_CLIENT_SECRET
  • LINKEDIN_REFRESH_TOKEN (programmatic refresh)
  • LINKEDIN_AUTHOR_URN (company page or member)

For OAuth flow details and scopes, refer to the LinkedIn docs on authorization code and programmatic refresh tokens. This endpoint describes how to mint refresh tokens that you can rotate without manual sign in.

Query Notion for due posts

Query the Notion database for rows whose Publish Date is due and Status equals Ready. The official API reference is documented under Notion database query.

curl -sSL https://api.notion.com/v1/databases/$NOTION_DATABASE_ID/query \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        {"property": "Status", "select": {"equals": "Ready"}},
        {"property": "Publish Date", "date": {"on_or_before": "now"}},
        {"property": "Channel", "select": {"equals": "LinkedIn"}}
      ]
    },
    "sorts": [{"property": "Publish Date", "direction": "ascending"}],
    "page_size": 20
  }'

Parse results and extract Title, Body, Image URL, Publish Date, and the Notion page ID for idempotency.

Prepare content and upload media

Convert Notion rich text to plain text or Markdown. If you have an Image URL, upload it to LinkedIn assets and capture the URN. The UGC Posts API supports media posts by referencing an uploaded asset.

# Upload image to LinkedIn assets
curl -sSL -X POST "https://api.linkedin.com/media/upload" \
  -H "Authorization: Bearer $LINKEDIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "initialize": {
      "owner": "'$LINKEDIN_AUTHOR_URN'",
      "recipes": ["urn:li:digitalmediaRecipe:feedshare-image"],
      "serviceRelationships": [{"relationshipType": "OWNER", "identifier": "urn:li:userGeneratedContent"}]
    }
  }'

Capture the returned asset URN for the post. For text-only posts, you can skip media upload.

Publish with LinkedIn UGC Posts

The UGC Posts API creates organic posts for members and organizations. See the official documentation in the LinkedIn developer docs.

curl -sSL -X POST "https://api.linkedin.com/v2/ugcPosts" \
  -H "Authorization: Bearer $LINKEDIN_ACCESS_TOKEN" \
  -H "X-Restli-Protocol-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "'$LINKEDIN_AUTHOR_URN'",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
      "com.linkedin.ugc.ShareContent": {
        "shareCommentary": {"text": "{{BODY}}"},
        "shareMediaCategory": "NONE"
      }
    },
    "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"}
  }'

For an image post, set shareMediaCategory to IMAGE and include a media array with your asset URN.

Build the OpenClaw playbook

Define a playbook that pulls due posts, runs approvals, and publishes. The structure below is a simplified example.

# playbooks/notion-to-linkedin.yaml
version: 1
meta:
  id: notion-to-linkedin
  description: Publish LinkedIn posts from Notion with approvals and retries

triggers:
  - type: schedule
    cron: "*/10 * * * *" # poll every 10 minutes

jobs:
  - id: ingest-notion
    steps:
      - id: fetch
        run: http.request
        with:
          method: POST
          url: https://api.notion.com/v1/databases/${NOTION_DATABASE_ID}/query
          headers:
            Authorization: Bearer ${NOTION_TOKEN}
            Notion-Version: "2022-06-28"
            Content-Type: application/json
          body:
            filter:
              and:
                - property: Status
                  select: { equals: Ready }
                - property: Publish Date
                  date: { on_or_before: now }
                - property: Channel
                  select: { equals: LinkedIn }
            sorts:
              - property: Publish Date
                direction: ascending
            page_size: 20

      - id: normalize
        run: utils.map
        with:
          input: "${steps.fetch.body.results}"
          script: |
            function toText(rt){
              if(!rt || !rt.length) return "";
              return rt.map(r=>r.plain_text).join("");
            }
            return input.map(page=>({
              id: page.id,
              title: toText(page.properties.Title.title),
              body: toText(page.properties.Body.rich_text),
              imageUrl: page.properties["Image URL"].url,
              publishAt: page.properties["Publish Date"].date?.start
            }));

      - id: due-filter
        run: utils.filter
        with:
          input: "${steps.normalize.output}"
          script: |
            const now = new Date().toISOString();
            return input.filter(p => p.publishAt && p.publishAt <= now);

      - id: enqueue
        run: queue.push
        with:
          items: "${steps.due-filter.output}"
          queue: linkedin-publish

  - id: approve-and-publish
    concurrency: 2
    steps:
      - id: approval
        run: approvals.request
        with:
          channel: "#content-approvals"
          title: "LinkedIn post: ${item.title}"
          body: "${item.body}"
          timeout: "2h"
          on_timeout: reject

      - id: publish
        when: "${steps.approval.status} == 'approved'"
        run: http.request
        retry:
          max_attempts: 5
          backoff: exponential
          on_codes: [429, 500, 502, 503]
        with:
          method: POST
          url: https://api.linkedin.com/v2/ugcPosts
          headers:
            Authorization: Bearer ${LINKEDIN_ACCESS_TOKEN}
            X-Restli-Protocol-Version: "2.0.0"
            Content-Type: application/json
            Idempotency-Key: "${item.id}"
          body:
            author: "${LINKEDIN_AUTHOR_URN}"
            lifecycleState: PUBLISHED
            specificContent:
              com.linkedin.ugc.ShareContent:
                shareCommentary:
                  text: "${item.body}"
                shareMediaCategory: NONE
            visibility:
              com.linkedin.ugc.MemberNetworkVisibility: PUBLIC

      - id: mark-done
        run: notion.update
        with:
          page_id: "${item.id}"
          token: "${NOTION_TOKEN}"
          properties:
            Status:
              select: { name: Paused }

policies:
  approvals:
    required: true
  budgets:
    max_requests_per_minute: 30

This example uses two jobs: one polls and enqueues, the other approves and publishes. The Idempotency-Key header prevents accidental duplicates when retries occur.

Add rate limits and idempotency

LinkedIn APIs can return 429 when you post too quickly. Protect yourself by applying a limiter per author and using exponential backoff. Use the Notion page ID as a stable idempotency key so a single row never creates two posts.

If your content includes media, upload assets once and cache the URN on the Notion page. On retry, reuse the URN instead of reuploading, which saves rate budget.

Schedule and concurrency

Choose a polling interval that fits your cadence. For most teams, every 10 minutes is fine. Set job concurrency to 2 or 3 to avoid flooding. If you run both organic and paid workflows, isolate queues so creative publishing does not compete with attribution tasks.

Observability and alerts

Instrument the pipeline with structured logs. Emit events when approvals time out, when publication succeeds, and when retries give up. Route incidents into your on call channel with a short template that includes the Notion page link and the last error message. This is where agent analytics help, and we have a dedicated guide on instrumentation in more from the ButterGrow blog.

Policy and approvals

Approvals create accountability. Keep approval timeouts short enough that missed posts are obvious, but long enough to handle business hours. Require a reason when an approver rejects a post, and store it back on the Notion page for audit.

Variations and extensions

  • Content generation: add a pre step that drafts body text from a headline using an AI agent, then request approval.
  • Multi channel: route Instagram or X posts to their own queues, using the Channel select.
  • Slotting: if multiple posts are due at the same minute, distribute them across the hour to avoid sudden bursts.

These extensions keep the pipeline flexible without breaking reliability.

Validation checklist

Before you ship, run through this list.

  • Notion rows must be Ready and targeted to LinkedIn.
  • Publish Date must be set to an ISO timestamp.
  • Image URLs must be reachable and safe to reuse.
  • The LinkedIn author URN must be correct for your page or member.
  • The OAuth token must have valid scopes for UGC posts.
  • Approval gate must be reachable and staffed.

Common pitfalls

  • Rich text can include emojis and links that break length limits. Normalize and trim before publishing.
  • Image uploads may fail if the mime type is not allowed. Probe headers and reject early.
  • Posting from a member versus a company page requires different author URNs. Double check the value.
  • Time zones cause scheduling drift. Normalize Publish Date to UTC in Notion and stick with a single zone.
  • Credentials stored in plaintext are a security risk. Use secrets and rotate regularly.

Publishing at scale is a reliability problem first. Autonomous agents help, but guardrails are the difference between smooth delivery and noisy incidents.

When you are ready to try this in your own account, you can spin up a hosted assistant and follow the onboarding guide. That page walks you through keys, runners, and the first playbook.

Create a repeatable path from idea to publish. Small details like idempotency and rate caps will keep your calendar running even when APIs return errors. The goal is consistent output with low manual effort.

ButterGrow gives you hosted OpenClaw assistants, policy controls, and observability designed for marketing teams.

Power users often ask how this compares to DIY scripts. The short version is that guardrails, approvals, and multi tenant credentials make production safer. The onboarding guide and FAQ explain where hosted runners and audit logs help you ship with fewer incidents.

Publish reliably, measure outcomes, and iterate on your calendar with small experiments. The pipeline above is a strong base for automation across channels.

ButterGrow can help you automate this workflow end to end. Try the hosted OpenClaw assistant and follow get started in minutes to provision your workspace. If you are curious about capabilities, the AI marketing automation features section shows how approvals, budgets, and agent pools work together.

References

Frequently Asked Questions

How do I structure a Notion database for LinkedIn scheduling?+

Create properties for Title, Body, Image URL, Publish Date, Channel, and Status. Use a select or checkbox to mark Ready, and keep drafts separate. The tutorial's mapping table shows how these fields align to the LinkedIn UGC post payload.

Which LinkedIn API should I use to publish organic posts?+

Use the UGC Posts API for rich organic posts with text and media. Authenticate with OAuth and include the author URN for your company page or member. The References section links to the official docs.

How can I add an approval step before publishing?+

Insert an approval gate in the OpenClaw playbook between Notion fetch and LinkedIn publish. Route approvals to Slack or email, enforce timeouts, and retry with backoff. The sample YAML includes a minimal policy block.

What is the best way to handle rate limits and retries?+

Throttle outbound calls with a per-author limiter and apply exponential backoff on 429 or 5xx. Persist job state to avoid duplicate publishing. The tutorial shows a retry policy and idempotency key pattern.

Can I schedule posts automatically from the Publish Date field?+

Yes. Use a scheduler to poll for rows whose Publish Date is due and Status equals Ready. Queue them to your runner with a concurrency cap. The article includes a scheduling example that reads ISO timestamps from Notion.

How do I map Notion rich text and images to LinkedIn?+

Convert Notion rich text to plain text or Markdown, upload images to LinkedIn's assets endpoint, then reference the asset in the UGC post. The code samples demonstrate a safe transform pipeline.

Ready to try ButterGrow?

See how ButterGrow can supercharge your growth with a quick demo.

Book a Demo