API reference

Integration sources

Register an integration source#

POST/v1/integration_sourcesScopeintegrations:write

Registers a connected store or site, or refreshes the one that already has this platform and external_id in the mode of the key (an upsert). A plugin calls it once when the user clicks "connect", stores id and source_key, and uses only the source key from then on. Calling it again is safe and is how a plugin reports a new version or new emits.

201 with source_key and signing_secret when the source was created; 200 without secrets when it existed. An account can have at most 50 sources per mode.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

platformstringRequired
Platform slug.
external_idstringRequired
The platform's stable identifier of the store or site.
1 to 255 characters
namestringOptional
Display name. Defaults to the platform and the identifier.
1 to 120 characters
urlstring or nullOptional
Public address of the store or site.
Up to 2048 characters
plugin_versionstring or nullOptional
Version of the plugin.
Up to 64 characters
platform_versionstring or nullOptional
Version of the platform.
Up to 255 characters
emitsarray of stringsOptional
Event types the plugin is able to send.

Responses

200
The source existed and was refreshed. No secrets.
201
The source was created. source_key and signing_secret are included, this once.
400
Bad request.
parameter_missing parameter_invalid invalid_json integration_source_limit_reached
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/integration_sources

curl https://api.omnimessage.co/v1/integration_sources \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "woocommerce",
    "external_id": "shop.example.com",
    "name": "Acme Shop",
    "url": "https://shop.example.com/",
    "plugin_version": "0.1.0",
    "platform_version": "woocommerce/10.1 wordpress/7.0",
    "emits": [
      "order.created",
      "order.paid",
      "order.shipped",
      "cart.abandoned"
    ]
  }'

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.1.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z"
}

List integration sources#

GET/v1/integration_sourcesScopeintegrations:read

Returns the integration sources of the key mode, newest first. Secrets are not included.

Query parameters

limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of sources.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/integration_sources

curl https://api.omnimessage.co/v1/integration_sources \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
      "object": "integration_source",
      "mode": "live",
      "platform": "woocommerce",
      "external_id": "shop.example.com",
      "name": "Acme Shop",
      "url": "https://shop.example.com/",
      "status": "active",
      "plugin_version": "0.1.0",
      "platform_version": "woocommerce/10.1 wordpress/7.0",
      "emits": [
        "order.created",
        "order.paid",
        "order.shipped",
        "cart.abandoned"
      ],
      "enabled_events": [
        "order.paid",
        "order.shipped"
      ],
      "event_settings": {
        "cart.abandoned": {
          "delay_seconds": 3600
        }
      },
      "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
      "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
      "ingest_urls": {
        "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
        "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
      },
      "config_version": 12,
      "last_event_at": "2026-10-05T09:30:00.000Z",
      "created_at": "2026-10-01T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve the source of a source key#

GET/v1/integration_sources/currentAny valid API key

Returns the source the key belongs to: which events to send (enabled_events), how to behave (event_settings) and where the editor is (console_url, automation_url_template). The response carries ETag: "<config_version>"; poll at most once per five minutes with If-None-Match.

Authenticate with the **source key** (Authorization: Bearer om_src_…) that was returned when the source was created. An API key is answered with 403 scope_missing.

Headers

If-None-MatchstringOptional
The ETag of the copy you hold. When it is still current the answer is 304 without a body.

Responses

200
The source.
304
Not modified: the If-None-Match value is the current ETag. No body.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
Called with an API key instead of a source key, or the source is disabled.
scope_missing ip_not_allowed account_suspended source_disabled
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/integration_sources/current

curl https://api.omnimessage.co/v1/integration_sources/current \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.1.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z"
}

Describe the source of a source key#

PATCH/v1/integration_sources/currentAny valid API key

Lets a plugin report its name, address, versions and the events it can send. Only the fields you send are changed. The status and the secrets cannot be changed with a source key.

Authenticate with the **source key** (Authorization: Bearer om_src_…) that was returned when the source was created. An API key is answered with 403 scope_missing.

Request body

namestringOptional
Display name.
1 to 120 characters
urlstring or nullOptional
Public address.
Up to 2048 characters
plugin_versionstring or nullOptional
Version of the plugin.
Up to 64 characters
platform_versionstring or nullOptional
Version of the platform.
Up to 255 characters
emitsarray of stringsOptional
Replaces the event types the plugin is able to send.

Responses

200
The updated source.
400
Bad request.
parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
Called with an API key instead of a source key, or the source is disabled.
scope_missing ip_not_allowed account_suspended source_disabled
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

PATCH/v1/integration_sources/current

curl -X PATCH https://api.omnimessage.co/v1/integration_sources/current \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plugin_version": "0.2.0",
    "emits": [
      "order.created",
      "order.paid",
      "order.shipped",
      "cart.abandoned",
      "form.submitted"
    ]
  }'

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.2.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z"
}

Retrieve an integration source#

GET/v1/integration_sources/{id}Scopeintegrations:read

Returns one integration source, with the same ETag as the source key sees. Secrets are not included.

Path parameters

idstringRequired
Integration source ID.

Headers

If-None-MatchstringOptional
The ETag of the copy you hold. When it is still current the answer is 304 without a body.

Responses

200
The source.
304
Not modified: the If-None-Match value is the current ETag. No body.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/integration_sources/{id}

curl https://api.omnimessage.co/v1/integration_sources/src_9Kd2mQ5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.1.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z"
}

Update an integration source#

PATCH/v1/integration_sources/{id}Scopeintegrations:write

Changes the description of a source, disables or enables it, replaces the secret native webhooks are verified with, or changes how its events are treated. Only the fields you send are changed.

Path parameters

idstringRequired
Integration source ID.

Request body

namestringOptional
Display name.
1 to 120 characters
urlstring or nullOptional
Public address.
Up to 2048 characters
plugin_versionstring or nullOptional
Version of the plugin.
Up to 64 characters
platform_versionstring or nullOptional
Version of the platform.
Up to 255 characters
emitsarray of stringsOptional
Replaces the event types the plugin is able to send.
statusstringOptional
disabled refuses the source key and the native webhooks until it is set back to active.
Possible valuesactivedisabled
signing_secretstringOptional
Replaces the secret native webhooks are verified with. Needed for Shopify, which signs with its own key. Write-only.
8 to 255 characters
settingsobjectOptional
How events of this source are treated.
Show child attributesHide child attributes
- contact_syncbooleanOptional
  Upsert the customer of every event into Contacts. Default true.
- consent_modestringOptional
  implied (default): transactional automations send unless the event says consent.transactional: false. explicit: they need true.
  Possible valuesimpliedexplicit
- store_all_eventsbooleanOptional
  Report enabled_events: ["*"], so that the plugin sends every event (debugging).

Responses

200
The updated source.
400
Bad request.
parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

PATCH/v1/integration_sources/{id}

Example

curl -X PATCH https://api.omnimessage.co/v1/integration_sources/src_9Kd2mQ5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Shop (main store)"
  }'

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop (main store)",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.1.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z"
}

Delete an integration source#

DELETE/v1/integration_sources/{id}Scopeintegrations:write

Deletes the source with its automations and receipts, and cancels its scheduled runs. The source key stops working at once. Messages that were already sent stay.

Path parameters

idstringRequired
Integration source ID.

Responses

200
The source was deleted.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

DELETE/v1/integration_sources/{id}

curl -X DELETE https://api.omnimessage.co/v1/integration_sources/src_9Kd2mQ5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "deleted": true
}

Roll the key of an integration source#

POST/v1/integration_sources/{id}/roll_keyScopeintegrations:write

Issues a new source_key and signing_secret. The old ones stop working at once: update the plugin and the platform webhook right away.

Path parameters

idstringRequired
Integration source ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The source with its new secrets.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/integration_sources/{id}/roll_key

curl -X POST https://api.omnimessage.co/v1/integration_sources/src_9Kd2mQ5vB8cX1zL0pK3j/roll_key \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "object": "integration_source",
  "mode": "live",
  "platform": "woocommerce",
  "external_id": "shop.example.com",
  "name": "Acme Shop",
  "url": "https://shop.example.com/",
  "status": "active",
  "plugin_version": "0.1.0",
  "platform_version": "woocommerce/10.1 wordpress/7.0",
  "emits": [
    "order.created",
    "order.paid",
    "order.shipped",
    "cart.abandoned"
  ],
  "enabled_events": [
    "order.paid",
    "order.shipped"
  ],
  "event_settings": {
    "cart.abandoned": {
      "delay_seconds": 3600
    }
  },
  "console_url": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations",
  "automation_url_template": "https://omnimessage.co/console/integrations/src_9Kd2mQ5vB8cX1zL0pK3j/automations/{event_type}",
  "ingest_urls": {
    "woocommerce": "https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j",
    "shopify": "https://api.omnimessage.co/v1/ingest/shopify/src_9Kd2mQ5vB8cX1zL0pK3j"
  },
  "config_version": 12,
  "last_event_at": "2026-10-05T09:30:00.000Z",
  "created_at": "2026-10-01T08:00:00.000Z",
  "source_key": "om_src_N7bT4xK1mQ8wE5rY2uI9oP3aS6dF0gHj",
  "signing_secret": "isec_Zk8vQ2mX5cB7nL0pR3tY6wA9dF1gH4jKN7bT4xK1"
}