# Connect event sources and AI tools.

CalendarDrop turns event information into editable WordPress drafts. An automation or AI tool that can make an authenticated HTTP request can submit event text to your WordPress site's CalendarDrop webhook.

This guide describes CalendarDrop 1.3.0. [Read the web version](https://calendardrop.pennerstrategy.com/integrations), [get setup help](https://calendardrop.pennerstrategy.com/help), or [get the WordPress plugin](https://wordpress.org/plugins/calendardrop/).

## Is this the right connection?

Use this workflow when you have permission to process incoming event details and want an editor to review drafts on a WordPress site. A community calendar, venue or local publication can use it to reduce repeated event entry.

- With The Events Calendar active, CalendarDrop creates native event drafts with dates, times and other extracted details.
- Without The Events Calendar, it creates ordinary WordPress draft posts with event metadata. Subscription credits still apply to those created drafts.
- CalendarDrop does not publish imports automatically. Review the source against the draft before publishing. AI can omit or misinterpret details.
- CalendarDrop adds a manual Google Calendar event link to ordinary posts with event metadata. It also provides individual `.ics` exports for publicly viewable, unprotected posts and The Events Calendar events. These are manual add/export options, not connected calendar accounts or automatic synchronization. Check the imported date and time in the destination calendar.

If your goal is to write directly to Google Calendar or Outlook, continuously synchronize calendars, or insert an already structured event without AI extraction, this webhook is not that connection. There is no dedicated CalendarDrop MCP server or agent SDK described here. Use your tool's ordinary HTTP integration.

## Set up the WordPress site

1. Install and activate CalendarDrop. Activate The Events Calendar if you want native calendar events. In WordPress **Settings → General**, select a named city timezone such as Los Angeles.
2. Choose how to pay for processing. **My own AI provider and billing** uses the provider, model and credentials configured in CalendarDrop's settings; a CalendarDrop subscription is not required. **CalendarDrop subscription allowance** includes processing and uses your site's event credits.
3. For the allowance option, open **CalendarDrop → Subscription**. Follow the account connection steps for your trial or paid license. Then select **CalendarDrop subscription allowance** and choose **Save processing mode**. Connecting an account alone does not switch the mode. [See the full connection steps](https://calendardrop.pennerstrategy.com/help).
4. Open **CalendarDrop → Settings → Advanced Integrations → Technical Webhook Details**. Copy **Webhook Target URL** and configure the **Secret Token** in your integration's secure credential store. Use the generated URL because WordPress permalink settings can change its form.
5. Authorize the integration for the intended source and site. Start with one fictional event, inspect the response and review the resulting draft. Even a test import can use provider processing and a draft credit.

Only the site owner or an authorized administrator should connect an integration. Do not paste webhook secrets, account connection codes, license keys, provider keys or passwords into a chat or model prompt. Configure authentication outside the model's event text. If a webhook secret is exposed, regenerate it in WordPress and update the authorized integration.

## Submit event text

Send **POST** to the copied WordPress webhook URL, usually `https://your-wordpress-site.example/wp-json/calendardrop/v1/ingest`.

Set these headers in the integration:

```http
Content-Type: application/json
X-CalendarDrop-Secret: <secret supplied by the credential store>
```

Example JSON body, using a fictional event:

```json
{
  "subject": "Fictional event submission",
  "text": "Paper Lantern Making Circle. July 16, 2038, 6:00 PM to 7:15 PM, America/Los_Angeles. Venue: Alder Workshop Room. Organizer: Fictional Lantern Collective. Admission: Free. Website: https://example.org/lantern-circle. Bring plain paper. Materials provided."
}
```

`text` is the event source. Include the actual event title, date, local time, location and other available details there. `subject` is an optional log label, not a substitute for the event body. An optional `sender` string can carry the submitting sender; omit it if it is not needed. If no event website is extracted, the plugin may use the sender's non-consumer email domain as a fallback website, so include the event's real URL when known.

The webhook also accepts form fields and common email-forwarding aliases: `body-plain`, `stripped-text`, `TextBody`, `text`, then `body`, in that order. Send one body field, as a string. Subject aliases are `subject` and `Subject`; sender aliases are `sender`, `from` and `From`. An email-forwarding service must be configured separately; CalendarDrop does not supply a mailbox.

The supported input is source text for extraction. This route does not accept an `events` array for direct insertion, fetch a URL's contents, or process attachments merely because their names or links appear in the body. Use the upload workflow for files. Use the secret header rather than placing a secret in a URL that could be logged or shared.

## Limits and credits

- Subscription text must be nonempty valid UTF-8, at most **30,000 characters** and **120,000 bytes**. A response can contain up to **30 events**. Make sure your allowance covers the expected number of new drafts.
- Own-provider webhook requests remain subject to your host and provider limits. The subscription text cap is not a promise about every own-provider configuration.
- One new subscription draft uses one credit. Skipped duplicates and failed draft creations release their reservations after WordPress confirms the outcome. An empty result uses no draft credits. A flagged duplicate that creates a new review draft is still a new draft.
- Processing limits are separate from draft credits. Repeated attempts, service capacity or an account needing review can prevent a new import even when credits remain. No throughput or unlimited retry guarantee is made.
- Send one request at a time per site. Subscription imports use a local lock while creating drafts and confirming outcomes.

See [current plans](https://calendardrop.pennerstrategy.com/) and [service terms](https://calendardrop.pennerstrategy.com/terms) before choosing a paid allowance.

## Read the result before taking another action

A successful response contains event IDs, per-event results and summary counts. This illustrative subset shows one created draft; actual results include additional fields:

```json
{
  "status": "success",
  "event_id": 123,
  "events_created": 1,
  "events_merged": 0,
  "events_skipped": 0,
  "events_failed": 0,
  "total_events": 1,
  "events": [
    {
      "event_id": 123,
      "status": "success",
      "message": "Event imported successfully."
    }
  ]
}
```

**HTTP 200 alone does not mean every event succeeded.** Inspect `events_failed`, the other counts and each item in `events`. Event statuses can include `success`, `fallback_success`, `skipped`, `merged` and `error`. The overall status can also be `batch_success`. Messages are for people and may change; do not use their exact wording as a machine contract. An `edit_link` can be empty for an unauthenticated webhook caller. Review drafts through WordPress.

For subscription imports, `replayed: true` means CalendarDrop returned an existing result. It retains the original counts, which do not describe new creations on this request. A `subscription_notice` can mean drafts were saved but their credit confirmation is pending. Check WordPress and choose **CalendarDrop → Subscription → Retry pending confirmations** instead of resubmitting just to confirm credits.

## Duplicates, interruptions and errors

Default duplicate handling skips a matching event. The plugin uses title/date-based checks, not an event ID supplied by your integration. Optional **flag** handling creates a separate review draft; **merge** updates an existing draft and skips non-drafts. Check your site's setting before automating submissions. Own-provider mode can make an AI request before identifying a duplicate.

The WordPress webhook does not accept a caller-controlled idempotency key. Subscription mode derives its own source, site, timezone and date identity and can recover recorded results. Do not assume an indefinite exactly-once guarantee across changed text, dates or site configuration.

If a request times out, stop automatic retries. Check the import log, drafts and pending confirmations first. Preserve the source and response. Follow the reported retry instructions; if the outcome remains unclear, contact support before altering the source or sending it again.

- **400:** configuration is missing or the text body is empty. Plugin errors generally contain an `error` string. Correct the request or site setup first.
- **401 or 403:** authentication or permission was refused. WordPress normally returns `code`, `message` and `data.status`. Verify the target site and secret without exposing them in logs.
- **500 or 502:** extraction, draft creation or the subscription request failed. Read the error and inspect WordPress before retrying. A service limit can surface through this wrapper; underlying service status codes are not guaranteed to pass through.
- Other responses can come from the host, firewall or WordPress security plugins. Keep the status and a sanitized response for diagnosis.

## File integrations

For a person submitting files, use **Upload Flyer** or the optional private upload page. Subscription mode accepts PNG, JPEG, WebP and native PDFs up to **4 MiB**. Text-based `.docx` files use extracted document text, subject to the text limit; embedded images are not the document's text source. The plugin's default decoded upload cap is **10 MiB**, and your host can impose a smaller request limit.

An authorized file automation can use the separately enabled WordPress route `POST /wp-json/calendardrop/v1/upload-flyer`. Configure the correct REST URL for your WordPress permalink settings. The **Private Upload URL** shown in settings opens the human upload page; it is not the REST target. The file route has a different header, `X-CalendarDrop-Upload-Secret`, and uses the private upload link's secret, not the text webhook secret. Keep that secret in the integration's credential store. Send JSON string fields `file_data` (base64 file bytes or a base64 data URI), `file_name` and `file_type` (MIME type). This is not a multipart upload. Send the complete original file, not a first-page preview as a substitute for a PDF. Base64 increases the request size.

The private upload route defaults to 20 requests per hour per IP-based bucket; site configuration can change that limit. This limit does not describe the text webhook. Its success response includes `success: true` and the import result; errors generally return HTTP 400 with an `error` message. Authentication and host-level errors can differ. Apply the same draft, partial-failure and retry checks as above.

## Permission and data handling

Submit only material you have permission to process. Keep unrelated correspondence, confidential records and secrets out of event source text. An agent should not choose a destination site, connect a paid account, or start chargeable imports beyond its owner's authorization.

In subscription mode, the selected source passes through CalendarDrop to Google Gemini for extraction. WordPress stores drafts and may retain uploads and import logs. CalendarDrop retains extracted results for recovery and separate account, billing and usage records. Own-provider mode sends extraction requests to the provider configured in WordPress. Read the [data-use details](https://calendardrop.pennerstrategy.com/privacy) for retention and provider handling.

For help, email [josh@pennerstrategy.com](mailto:josh@pennerstrategy.com?subject=CalendarDrop%20integration%20help) with the CalendarDrop and WordPress versions, request time, status and a sanitized error. Do not send authentication values or confidential source documents. [Back to CalendarDrop](https://calendardrop.pennerstrategy.com/).