Partner integration · Secure intake

WorldsAid transmission connector for Sesame

Sesame sends source-linked disaster leads to WorldsAid. The connector only receives them into the existing investigation queue; it never sends data onward and cannot publish, amend or delete a story.

Implemented queue boundary

Accepted submissions receive human_review status and publication: not_published. WorldsAid independently verifies sources, figures, location, imagery and editorial placement.

Provisioning still required

The receive-only ingress is implemented at POST /api/connectors/sesame/ingress, but remains disabled pending a dedicated ingress Bearer and confirmation that Sesame can store it securely. No authenticated production transmission has succeeded yet.

Download the Node.js reference connector OpenAPI 3.0 specification All API documentation

Connection

Sesame → WorldsAid receive-only ingress

Method	`POST`
Ingress	`https://worldsaid.com/api/connectors/sesame/ingress`
Authentication	`Authorization: Bearer <SESAME_INGRESS_CREDENTIAL>`
Current availability	Implemented but disabled pending secure provisioning.

The ingress credential authenticates Sesame only and grants no editorial access. After validation, WorldsAid itself creates an unverified observation with human_review and not_published. The connector performs no outbound HTTP request.

Store the ingress token in Sesame’s encrypted secret store. Never put it in a prompt, source file, URL, request body or application log. There is no X-API-Key alternative.

Payload contract

Field	Required	Contract
`external_id`	Yes	Sender-stable string; maximum 120 characters.
`title`	Yes	String, 10–300 characters.
`summary`	Yes	String, 30–4,000 characters. State the new or changed facts.
`source_urls`	Yes	Array of 1–8 unique HTTPS URLs. This carries ReliefWeb, GDACS or another authoritative source URL.
`observed_at`	Yes	ISO 8601 date-time represented by the source observation.
`urgency`	Yes	`low`, `moderate`, `high` or `critical`.
`suggested_action`	Yes	`investigate`, `new_story` or `update_story`.
`target_story_id`	Conditional	Required for `update_story`; maximum 80 characters.
`source_name`	No	Source organization; maximum 160 characters.
`event_type`	No	Disaster type; maximum 100 characters.
`country_codes`	No	Up to 12 unique ISO 3166-1 alpha-2 codes.
`latitude`, `longitude`	No	Valid coordinate pair. Supply both or neither.

Action selection

Use new_story when the source describes an event missing from WorldsAid.
Use update_story with target_story_id when facts or figures changed for a known story.
Use investigate when Sesame cannot safely determine whether the item is new or an update.

Reference client

The downloadable Node.js 22+ connector reads JSON from standard input and credentials only from protected environment variables or programmatic options.

export WORLDSAID_SESAME_INGRESS_TOKEN='<SECRET_FROM_SECURE_STORE>'

node worldsaid-sesame.mjs < transmission.json

The connector writes only the non-secret receipt to standard output. Failed responses are returned without echoing the Bearer credential.

Minimal transmission

{
  "external_id": "reliefweb-report-123456",
  "title": "Flood assessment reports changed displacement figures",
  "summary": "The latest source reports revised displacement figures and requires independent verification against the existing WorldsAid record.",
  "source_urls": ["https://reliefweb.int/example-report"],
  "observed_at": "2026-10-21T13:00:00Z",
  "urgency": "high",
  "suggested_action": "investigate"
}

Receipts, changes and duplicates

A new valid transmission returns HTTP 202 with a transmission_id, observation_id, status: human_review, publication: not_published and the receipt time.

An exact duplicate—same authenticated sender, external_id and normalized content hash—returns HTTP 200 with the existing identifiers and duplicate: true. An existing story does not suppress changed information: materially changed normalized content produces a new hash and a new queue item. Sesame should include the source observation time in its stable external identifier when helpful for auditability.

The limiter allows a burst of 12 requests and refills at two requests per minute. HTTP 429 includes Retry-After.

Owner provisioning checklist

Create a dedicated high-entropy ingress Bearer in an approved password manager or secret manager; do not send it through chat or email.
Store it as the WorldsAid secret WORLDSAID_SESAME_INGRESS_API_KEYS and in Sesame’s confirmed encrypted secret facility.
Enable WORLDSAID_SESAME_INGRESS_ENABLED.
Send a synthetic test transmission and confirm a 202 receipt with human_review and not_published.
Repeat the same payload and confirm the duplicate 200 response.
Send a changed observation using the same source-event identity and confirm that it creates a new queue item.

Return to WorldsAid