Web Events

The URLs that start a job when they are called, and calling one.

Prefix /cdna-api/hooks ReferenceWebEvent model GuideCustom endpoints with synchronous jobs

About web events

A web event gives its job a URL: /cdna-api/webhook/{slug}. A call queues a run and answers at once, unless the job is synchronous; then the run happens inside the request and the job’s HTTP response action writes the answer. The examples here leave out slug, because without authentication it is the only thing protecting the URL.

URL /cdna-api/webhook/

Not under /cdna-api/hooks/. Anything after the slug reaches the job as path parameters.

Custom endpoints with synchronous jobs

Authentication Off by default

Off, anyone with the URL can call it; on, only backend users can.

Custom endpoints with synchronous jobs

Synchronous Per job

Set on the job, not the web event. Only then can the job answer the caller.

Custom endpoints with synchronous jobs

Learn more

GuideCustom endpoints with synchronous jobs How-toCreate your own JSON endpoint with a synchronous job GuideEvents, what starts a job

List a job’s web events#

GET /cdna-api/hooks/web-events/{hook.id}

Lists the web events of one job.

Access: Admin users and integrations, with an OAuth access token or an API key.
Model: WebEvent, in the Reference

Parameters

hook.idpathrequired: integer; The job id.
propertiesquery: selector; The fields and relations to return, such as {id,methods,authenticationRequired}.
filtersquery: name=value; Any stored field, or a relation with a dot, such as authenticationRequired=0. Prefix the name with !, >, <, % or |. Use stored field names exactly as in the model, and compare totalCount with the unfiltered list's to confirm a filter applied.
orderByquery: string; field:ASC or field:DESC, comma-separated. Stored fields only.
limitquery: integer; Records per response: 100 when left out, at most 500. A larger value answers 400.
pagequery: integer; The page to return, counting from 1. offset works too.

Example

List a job’s web events

GET /cdna-api/hooks/web-events/56?limit=2&properties={id,methods,authenticationRequired} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "totalCount": 1,
  "data": [
    {
      "id": 32,
      "methods": [
        "post"
      ],
      "authenticationRequired": false
    }
  ]
}

Open in Postman docs Real response from this documentation site

Show a web event#

GET /cdna-api/hooks/web-event/{id}

Reads one web event by its id. Its slug is the secret part of its URL: keep it out of logs and front-end code unless the endpoint is meant to be public.

Access: Admin users and integrations, with an OAuth access token or an API key.
Model: WebEvent, in the Reference

Parameters

idpathrequired: integer; The web event id.
propertiesquery: selector; The fields and relations to return, such as {id,methods,authenticationRequired}.

Example

Show a web event

GET /cdna-api/hooks/web-event/32?properties={id,methods,authenticationRequired} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Response 200 OK

{
  "result": "success",
  "data": {
    "id": 32,
    "methods": [
      "post"
    ],
    "authenticationRequired": false
  }
}

Open in Postman docs Real response from this documentation site

Create a web event#

POST /cdna-api/hooks/web-event/{hook.id}

Adds a web event to a job. The URL works once the job is published.

Access: Admin users and integrations, with an OAuth access token or an API key.
Returns: The new web event under data.webEvent, with its slug, and a message.

Parameters

hook.idpathrequired: integer; The job id.
retrieveUnpublishedquery: 1; Needed while the job is unpublished, unless the admin shows unpublished records: without it the job is not found.
slugbody: string; The last part of the URL. Left out, a random one is made, which is safer than a readable name. Unique per site.
methodsbody: list; The HTTP methods the URL answers, such as ["post"]. get, put, post and delete by default.
authenticationRequiredbody: boolean; true lets only backend users (an API key, an OAuth token or an admin session) call it.

Example

Create a web event

POST /cdna-api/hooks/web-event/12 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "methods": [
    "post"
  ],
  "authenticationRequired": true
}

Open in Postman docs

Edit a web event#

PUT /cdna-api/hooks/web-event/{id}

Changes a web event. Fields left out keep their values.

Access: Admin users and integrations, with an OAuth access token or an API key.
Returns: The saved web event under data.webEvent, and a message.

Parameters

idpathrequired: integer; The web event id.
methodsbody: list; The HTTP methods the URL answers, such as ["post"]. get, put, post and delete by default.
authenticationRequiredbody: boolean; true lets only backend users (an API key, an OAuth token or an admin session) call it.

Example

Edit a web event

PUT /cdna-api/hooks/web-event/14 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "methods": [
    "post",
    "get"
  ],
  "authenticationRequired": true
}

Open in Postman docs

Delete a web event#

DELETE /cdna-api/hooks/web-event/{id}

Deletes a web event.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

idpathrequired: integer; The web event id.

Example

Delete a web event

DELETE /cdna-api/hooks/web-event/14 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Open in Postman docs

Check that a slug is free#

POST /cdna-api/hooks/web-event/check-slug

Answers {"result":"success"} when no web event on the site uses the slug, and an error with a message when one does.

Access: Admin users and integrations, with an OAuth access token or an API key.

Parameters

slugbodyrequired: string; The slug to check.
idbody: integer; A web event to leave out of the check, when renaming it.
sitebody: integer; The site to check in.

Example

Check that a slug is free

POST /cdna-api/hooks/web-event/check-slug HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

{
  "slug": "stock-lookup"
}

Open in Postman docs

Call a web event#

POST /cdna-api/webhook/{slug}

Starts the web event’s job. Any method the web event allows works. The path segments after the slug, the query, the headers and the body all reach the job through $event.

Access: Anyone. The route takes no credentials, by design.
Returns: Asynchronous: the queued run under data.batch. Synchronous: what the HTTP response action writes. A wrong slug, an unpublished job or a method not allowed: 404.

Parameters

slugpathrequired: string; The web event’s slug.
(more segments)path: string; Passed to the job as a list, read with $event->getPathParameters().
(query, headers, body): Passed as sent; $event->getBodyData() parses a JSON or form body.

With authentication off, which is the default, anyone who has the URL can start the job. It runs with its author’s permissions, and a synchronous run sees unpublished records. Keep the slug secret, or turn authentication on.

Example

Call a web event

POST /cdna-api/webhook/YOUR-WEB-EVENT-SLUG/stores/sydney?source=pos HTTP/1.1
Host: hub.coredna.com
Accept: application/json
Content-Type: application/json

{
  "sku": "ABC-123",
  "quantity": 2
}

Open in Postman docs

Learn more

GuideCustom endpoints with synchronous jobs How-toCreate your own JSON endpoint with a synchronous job

Objects ReferenceGenerated from the platform, so it is always current

API ReferenceEvery REST endpoint, in cURL, PHP, Python and JavaScript

Web Events

About web events

Learn more

List a job’s web events#

Parameters

Example

Show a web event#

Parameters

Example

Create a web event#

Parameters

Example

Edit a web event#

Parameters

Example

Delete a web event#

Parameters

Example

Check that a slug is free#

Parameters

Example

Call a web event#

Parameters

Example

Learn more