Create a queue's push subscription

Checked on the queue (queues.subscriptions.create), and for a workflow target workflows.runs.start on the workflow too, in one check; 400 at target.appId for an app that isn't in the queue's project, at target.workflow for a workflow the app has synced without, and 503 integration_unavailable while EZGH Workflows isn't connected. A queue has at most one subscription (409 subscription_exists). The answer holds an https target's signing secret, once; pull receivers can still receive from the queue, competing with the subscription.

POST

https://queues-api.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/subscriptions

View as Markdown

Authorization

apiKeyoptionalHTTP
oauthoptionalHTTP
sessionCookieoptionalAPI key in cookie

Path parameters

orgIdstringrequired
format: uuid
projectIdstringrequired
format: uuid

Header parameters

Idempotency-Keyoptionalstring
Makes a retry safe: the same key and request get the stored response.

pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

queueIdstringrequired
format: uuid
targetHttpsTargetorWorkflowTargetrequired
Where deliveries go: an HTTPS endpoint, or an EZGH Workflows workflow. The kind is fixed when the subscription is created; clients treat other kinds as unknown.
2 variants
One of the following:
HttpsTargethttps
View HttpsTarget schema →
3 properties
kindunknownrequired
urlstringrequired
format: uri, maxLength: 2048
timeoutSecondsoptionalinteger
How long a delivery may take.

maximum: 60, minimum: 1
Default: 30
WorkflowTargetworkflow
View WorkflowTarget schema →
5 properties
appIdstringrequired
The Workflows app's id (wfa_), in the queue's project.

format: uuid
kindunknownrequired
modestartorresumerequired
start: each message starts a run. resume: each message completes the waits (step.waitForMessage) of the app's runs waiting on its correlationAttribute's value, acked once any resumed; with none waiting yet, or without the attribute, it's retried with the backoff and then dead-lettered. Clients treat other modes as unknown.

workflowstringrequired
One of the app's workflows.

pattern: ^[A-Za-z0-9_-]{1,64}$
correlationAttributeoptionalstring
resume only, and required for it: the message attribute whose value (1-256 letters, digits and _ . : -) is the waits' key.

pattern: ^[A-Za-z0-9_.-]{1,64}$
batchSizeoptionalinteger
Messages per delivery: 1 for a workflow target (its default).

maximum: 10, minimum: 1
Default: 10
maxConcurrencyoptionalinteger
maximum: 100, minimum: 1
Default: 10
stateoptionalactiveorpaused
Default: "active"

Returns

201

The subscription, with its signing secret.

JSON

batchSizeintegerrequired
maximum: 10, minimum: 1
createdAtstringrequired
format: date-time
idstringrequired
format: uuid
maxConcurrencyintegerrequired
Deliveries in flight at once.

maximum: 100, minimum: 1
organizationIdstringrequired
projectIdstringrequired
queueIdstringrequired
The queue it consumes; fixed.

format: uuid
resourceNamestringrequired
slugstringrequired
qsb_ and 12 characters.
stateactiveorpausedrequired
statusobjectrequired
3 properties
- healthstringrequired
  healthy or failing; clients treat others as unknown.
- lastErrorDeliveryErrorornullrequired
  2 variants
  One of the following:
  DeliveryError
  View DeliveryError schema →
  4 properties
  atstringrequired
  format: date-time
  classstringrequired
  http, timeout, connection, refused, tls, internal (EZGH's own problem) or message (a workflow resume: the message has no usable correlation attribute, or no run was waiting); clients treat others as unknown.
  
  messagestringrequired
  At most 200 characters.
  
  statusoptionalinteger
  The endpoint's HTTP status, when it answered.
  
  null
- lastSuccessAtstring | nullrequired
  format: date-time
targetHttpsTargetorWorkflowTargetrequired
Where deliveries go: an HTTPS endpoint, or an EZGH Workflows workflow. The kind is fixed when the subscription is created; clients treat other kinds as unknown.
2 variants
One of the following:
HttpsTargethttps
View HttpsTarget schema →
3 properties
kindunknownrequired
urlstringrequired
format: uri, maxLength: 2048
timeoutSecondsoptionalinteger
How long a delivery may take.

maximum: 60, minimum: 1
Default: 30
WorkflowTargetworkflow
View WorkflowTarget schema →
5 properties
appIdstringrequired
The Workflows app's id (wfa_), in the queue's project.

format: uuid
kindunknownrequired
modestartorresumerequired
start: each message starts a run. resume: each message completes the waits (step.waitForMessage) of the app's runs waiting on its correlationAttribute's value, acked once any resumed; with none waiting yet, or without the attribute, it's retried with the backoff and then dead-lettered. Clients treat other modes as unknown.

workflowstringrequired
One of the app's workflows.

pattern: ^[A-Za-z0-9_-]{1,64}$
correlationAttributeoptionalstring
resume only, and required for it: the message attribute whose value (1-256 letters, digits and _ . : -) is the waits' key.

pattern: ^[A-Za-z0-9_.-]{1,64}$
updatedAtstringrequired
format: date-time
signingSecretstring | nullrequired
whsec_ and the key: verifies EZGH-Signature on deliveries. Shown once, never again; null on an Idempotency-Key replay, and for a workflow target (which has none).

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.