Webhooks - Webhooks | Signals docs

List webhook endpoints

GET

https://api.signals.pressone.africa/v1

/webhooks

List webhook endpoints › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

List webhook endpoints › Responses

Every webhook endpoint in the project.

WebhookEndpointList

WebhookEndpoint[] · required

GET/webhooks

curl https://api.signals.pressone.africa/v1/webhooks \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "created_by",
      "disabled_at": "2024-08-25T15:00:00Z",
      "disabled_reason": "disabled_reason",
      "events": [
        "string"
      ],
      "failover_url": "https://www.example.com/path/to/resource",
      "health": {
        "attempts": 0,
        "delivered": 0,
        "exhausted": 0,
        "failing_since": "2024-08-25T15:00:00Z",
        "failover_attempts": 0,
        "failover_delivered": 0,
        "last_attempt_at": "2024-08-25T15:00:00Z",
        "last_error": "last_error",
        "last_status_code": 0,
        "p50_ms": 0,
        "p95_ms": 0,
        "p99_ms": 0,
        "recent_attempts": 0,
        "recent_failures": 0,
        "retrying": 0,
        "status": "healthy",
        "window_hours": 0
      },
      "id": "id",
      "is_active": true,
      "previous_retires_at": "2024-08-25T15:00:00Z",
      "retained_events": 0,
      "retention_ends_at": "2024-08-25T15:00:00Z",
      "scope": {
        "id": "id",
        "name": "name",
        "type": "organization"
      },
      "secret_hint": "secret_hint",
      "secret_rotated_at": "2024-08-25T15:00:00Z",
      "timeout_seconds": 0,
      "url": "https://www.example.com/path/to/resource"
    }
  ]
}

json

application/json

Create a webhook endpoint

POST

https://api.signals.pressone.africa/v1

/webhooks

Create a webhook endpoint › Headers

Idempotency-Key

string · required

One nonblank key of at most 128 characters; a retry with the same key repeats the outcome.

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Create a webhook endpoint › Request Body

CreateWebhookEndpointRequest

events

string[] · required

scope_type

WebhookEndpointScopeType · enum · required

Enum values:

organization

trunk

subaccount

timeout_seconds

integer · int32 · min: 0 · required

url

string · uri · required

failover_url

string | null · uri

scope_id

string | null

Create a webhook endpoint › Responses

An idempotent replay; secret is null and secret_unavailable is true.

CreatedWebhookEndpoint

WebhookEndpoint · required

secret

string | null · required

secret_unavailable

boolean · required

POST/webhooks

curl https://api.signals.pressone.africa/v1/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "scope_id": "scope_id",
  "scope_type": "organization",
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}'

Example Request Body

{
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "scope_id": "scope_id",
  "scope_type": "organization",
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}

json

Example Responses

{
  "endpoint": {
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": "created_by",
    "disabled_at": "2024-08-25T15:00:00Z",
    "disabled_reason": "disabled_reason",
    "events": [
      "string"
    ],
    "failover_url": "https://www.example.com/path/to/resource",
    "health": {
      "attempts": 0,
      "delivered": 0,
      "exhausted": 0,
      "failing_since": "2024-08-25T15:00:00Z",
      "failover_attempts": 0,
      "failover_delivered": 0,
      "last_attempt_at": "2024-08-25T15:00:00Z",
      "last_error": "last_error",
      "last_status_code": 0,
      "p50_ms": 0,
      "p95_ms": 0,
      "p99_ms": 0,
      "recent_attempts": 0,
      "recent_failures": 0,
      "retrying": 0,
      "status": "healthy",
      "window_hours": 0
    },
    "id": "id",
    "is_active": true,
    "previous_retires_at": "2024-08-25T15:00:00Z",
    "retained_events": 0,
    "retention_ends_at": "2024-08-25T15:00:00Z",
    "scope": {
      "id": "id",
      "name": "name",
      "type": "organization"
    },
    "secret_hint": "secret_hint",
    "secret_rotated_at": "2024-08-25T15:00:00Z",
    "timeout_seconds": 0,
    "url": "https://www.example.com/path/to/resource"
  },
  "secret": "secret",
  "secret_unavailable": true
}

json

application/json

List webhook deliveries

GET

https://api.signals.pressone.africa/v1

/webhooks/deliveries

List webhook deliveries › query Parameters

endpoint

string

event_type

string

result

string · enum

Enum values:

delivered

retrying

exhausted

status_class

string · enum

Enum values:

2xx

4xx

5xx

none

attempt

integer · int32

from

string · date-time

to

string · date-time

limit

integer · int32 · min: 0

List webhook deliveries › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

List webhook deliveries › Responses

The deliveries matching the filter.

WebhookDeliveryList

WebhookDelivery[] · required

GET/webhooks/deliveries

curl https://api.signals.pressone.africa/v1/webhooks/deliveries \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "attempt": 0,
      "attempted_at": "2024-08-25T15:00:00Z",
      "call_sequence": 0,
      "duration_ms": 0,
      "endpoint_id": "endpoint_id",
      "endpoint_url": "https://www.example.com/path/to/resource",
      "error": "error",
      "event_id": "event_id",
      "event_type": "event_type",
      "id": "id",
      "max_attempts": 0,
      "next_retry_at": "2024-08-25T15:00:00Z",
      "replay_request_id": "replay_request_id",
      "replay_requested_by": "replay_requested_by",
      "replayable_until": "2024-08-25T15:00:00Z",
      "resource": {
        "id": "id",
        "label": "label",
        "type": "type"
      },
      "result": "delivered",
      "status_code": 0
    }
  ]
}

json

application/json

Read a webhook delivery

GET

https://api.signals.pressone.africa/v1

/webhooks/deliveries/{delivery_id}

Read a webhook delivery › path Parameters

delivery_id

string · required

Webhook delivery id

Read a webhook delivery › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Read a webhook delivery › Responses

The delivery with its attempts, request and response.

WebhookDeliveryDetail

attempt

integer · int32 · required

attempted_at

string · date-time · required

call_sequence

integer | null · int64 · required

duration_ms

integer | null · int32 · required

endpoint_id

string · required

endpoint_url

string · uri · required

error

string | null · required

event_id

string · required

event_type

string · required

id

string · required

max_attempts

integer · int32 · required

next_retry_at

string | null · date-time · required

replay_request_id

string | null · required

replay_requested_by

string | null · required

replayable_until

string | null · date-time · required

required

result

WebhookDeliveryResult · enum · required

Enum values:

delivered

retrying

exhausted

status_code

integer | null · int32 · required

WebhookDeliveryAttempt[] · required

request_body

string · required

object · required

response_excerpt

string | null · required

object | null · required

GET/webhooks/deliveries/{delivery_id}

curl https://api.signals.pressone.africa/v1/webhooks/deliveries/:delivery_id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "attempt": 0,
  "attempted_at": "2024-08-25T15:00:00Z",
  "call_sequence": 0,
  "duration_ms": 0,
  "endpoint_id": "endpoint_id",
  "endpoint_url": "https://www.example.com/path/to/resource",
  "error": "error",
  "event_id": "event_id",
  "event_type": "event_type",
  "id": "id",
  "max_attempts": 0,
  "next_retry_at": "2024-08-25T15:00:00Z",
  "replay_request_id": "replay_request_id",
  "replay_requested_by": "replay_requested_by",
  "replayable_until": "2024-08-25T15:00:00Z",
  "resource": {
    "id": "id",
    "label": "label",
    "type": "type"
  },
  "result": "delivered",
  "status_code": 0,
  "attempts": [
    {
      "attempt": 0,
      "attempted_at": "2024-08-25T15:00:00Z",
      "duration_ms": 0,
      "error": "error",
      "response_excerpt": "response_excerpt",
      "scheduled_for": "2024-08-25T15:00:00Z",
      "status_code": 0,
      "target": "primary"
    }
  ],
  "request_body": "request_body",
  "request_headers": {
    "key": "string"
  },
  "response_excerpt": "response_excerpt",
  "response_headers": {
    "key": "string"
  }
}

json

application/json

Retry one webhook delivery now

POST

https://api.signals.pressone.africa/v1

/webhooks/deliveries/{delivery_id}/retry

Retry one webhook delivery now › path Parameters

delivery_id

string · required

Webhook delivery id

Retry one webhook delivery now › Headers

Idempotency-Key

string · required

One nonblank key of at most 128 characters; a retry with the same key repeats the outcome.

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Retry one webhook delivery now › Responses

The new delivery attempt.

WebhookDelivery

attempt

integer · int32 · required

attempted_at

string · date-time · required

call_sequence

integer | null · int64 · required

duration_ms

integer | null · int32 · required

endpoint_id

string · required

endpoint_url

string · uri · required

error

string | null · required

event_id

string · required

event_type

string · required

id

string · required

max_attempts

integer · int32 · required

next_retry_at

string | null · date-time · required

replay_request_id

string | null · required

replay_requested_by

string | null · required

replayable_until

string | null · date-time · required

required

result

WebhookDeliveryResult · enum · required

Enum values:

delivered

retrying

exhausted

status_code

integer | null · int32 · required

POST/webhooks/deliveries/{delivery_id}/retry

curl https://api.signals.pressone.africa/v1/webhooks/deliveries/:delivery_id/retry \
  --request POST \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "attempt": 0,
  "attempted_at": "2024-08-25T15:00:00Z",
  "call_sequence": 0,
  "duration_ms": 0,
  "endpoint_id": "endpoint_id",
  "endpoint_url": "https://www.example.com/path/to/resource",
  "error": "error",
  "event_id": "event_id",
  "event_type": "event_type",
  "id": "id",
  "max_attempts": 0,
  "next_retry_at": "2024-08-25T15:00:00Z",
  "replay_request_id": "replay_request_id",
  "replay_requested_by": "replay_requested_by",
  "replayable_until": "2024-08-25T15:00:00Z",
  "resource": {
    "id": "id",
    "label": "label",
    "type": "type"
  },
  "result": "delivered",
  "status_code": 0
}

json

application/json

Read a webhook endpoint

GET

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}

Read a webhook endpoint › path Parameters

endpoint_id

string · required

Webhook endpoint id

Read a webhook endpoint › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Read a webhook endpoint › Responses

The webhook endpoint.

WebhookEndpoint

created_at

string · date-time · required

created_by

string | null · required

disabled_at

string | null · date-time · required

disabled_reason

string | null · required

events

string[] · required

failover_url

string | null · uri · required

WebhookEndpointHealth · required

id

string · required

is_active

boolean · required

previous_retires_at

string | null · date-time · required

retained_events

integer | null · int64 · min: 0 · required

retention_ends_at

string | null · date-time · required

WebhookEndpointScope · required

secret_hint

string · required

secret_rotated_at

string · date-time · required

timeout_seconds

integer · int32 · min: 0 · required

url

string · uri · required

GET/webhooks/{endpoint_id}

curl https://api.signals.pressone.africa/v1/webhooks/:endpoint_id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "created_at": "2024-08-25T15:00:00Z",
  "created_by": "created_by",
  "disabled_at": "2024-08-25T15:00:00Z",
  "disabled_reason": "disabled_reason",
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "health": {
    "attempts": 0,
    "delivered": 0,
    "exhausted": 0,
    "failing_since": "2024-08-25T15:00:00Z",
    "failover_attempts": 0,
    "failover_delivered": 0,
    "last_attempt_at": "2024-08-25T15:00:00Z",
    "last_error": "last_error",
    "last_status_code": 0,
    "p50_ms": 0,
    "p95_ms": 0,
    "p99_ms": 0,
    "recent_attempts": 0,
    "recent_failures": 0,
    "retrying": 0,
    "status": "healthy",
    "window_hours": 0
  },
  "id": "id",
  "is_active": true,
  "previous_retires_at": "2024-08-25T15:00:00Z",
  "retained_events": 0,
  "retention_ends_at": "2024-08-25T15:00:00Z",
  "scope": {
    "id": "id",
    "name": "name",
    "type": "organization"
  },
  "secret_hint": "secret_hint",
  "secret_rotated_at": "2024-08-25T15:00:00Z",
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}

json

application/json

Delete a webhook endpoint

DELETE

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}

Delete a webhook endpoint › path Parameters

endpoint_id

string · required

Webhook endpoint id

Delete a webhook endpoint › Headers

If-Match

string · required

The quoted revision the caller last read, so a concurrent change answers 412.

Idempotency-Key

string · required

One nonblank key of at most 128 characters; a retry with the same key repeats the outcome.

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Delete a webhook endpoint › Responses

The endpoint was deleted; a replay of the same request answers 204 again.

No data returned

Update a webhook endpoint

PATCH

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}

Update a webhook endpoint › path Parameters

endpoint_id

string · required

Webhook endpoint id

Update a webhook endpoint › Headers

If-Match

string · required

The quoted revision the caller last read, so a concurrent change answers 412.

Idempotency-Key

string · required

One nonblank key of at most 128 characters; a retry with the same key repeats the outcome.

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Update a webhook endpoint › Request Body

Every field is optional and at least one is required; a field left out keeps its value.

UpdateWebhookEndpointRequest

events

array | null

failover_url

string | null · uri

Null clears the failover URL; leaving the field out keeps it.

is_active

boolean | null

timeout_seconds

integer | null · int32 · min: 0

url

string | null · uri

Update a webhook endpoint › Responses

The endpoint after the change.

WebhookEndpoint

created_at

string · date-time · required

created_by

string | null · required

disabled_at

string | null · date-time · required

disabled_reason

string | null · required

events

string[] · required

failover_url

string | null · uri · required

WebhookEndpointHealth · required

id

string · required

is_active

boolean · required

previous_retires_at

string | null · date-time · required

retained_events

integer | null · int64 · min: 0 · required

retention_ends_at

string | null · date-time · required

WebhookEndpointScope · required

secret_hint

string · required

secret_rotated_at

string · date-time · required

timeout_seconds

integer · int32 · min: 0 · required

url

string · uri · required

PATCH/webhooks/{endpoint_id}

curl https://api.signals.pressone.africa/v1/webhooks/:endpoint_id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'If-Match: <string>' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "is_active": true,
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}'

Example Request Body

{
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "is_active": true,
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}

json

Example Responses

{
  "created_at": "2024-08-25T15:00:00Z",
  "created_by": "created_by",
  "disabled_at": "2024-08-25T15:00:00Z",
  "disabled_reason": "disabled_reason",
  "events": [
    "string"
  ],
  "failover_url": "https://www.example.com/path/to/resource",
  "health": {
    "attempts": 0,
    "delivered": 0,
    "exhausted": 0,
    "failing_since": "2024-08-25T15:00:00Z",
    "failover_attempts": 0,
    "failover_delivered": 0,
    "last_attempt_at": "2024-08-25T15:00:00Z",
    "last_error": "last_error",
    "last_status_code": 0,
    "p50_ms": 0,
    "p95_ms": 0,
    "p99_ms": 0,
    "recent_attempts": 0,
    "recent_failures": 0,
    "retrying": 0,
    "status": "healthy",
    "window_hours": 0
  },
  "id": "id",
  "is_active": true,
  "previous_retires_at": "2024-08-25T15:00:00Z",
  "retained_events": 0,
  "retention_ends_at": "2024-08-25T15:00:00Z",
  "scope": {
    "id": "id",
    "name": "name",
    "type": "organization"
  },
  "secret_hint": "secret_hint",
  "secret_rotated_at": "2024-08-25T15:00:00Z",
  "timeout_seconds": 0,
  "url": "https://www.example.com/path/to/resource"
}

json

application/json

List one endpoint's deliveries

GET

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}/deliveries

List one endpoint's deliveries › path Parameters

endpoint_id

string · required

Webhook endpoint id

List one endpoint's deliveries › query Parameters

event_type

string

result

string · enum

Enum values:

delivered

retrying

exhausted

status_class

string · enum

Enum values:

2xx

4xx

5xx

none

attempt

integer · int32

from

string · date-time

to

string · date-time

limit

integer · int32 · min: 0

List one endpoint's deliveries › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

List one endpoint's deliveries › Responses

The endpoint's deliveries matching the filter.

WebhookDeliveryList

WebhookDelivery[] · required

GET/webhooks/{endpoint_id}/deliveries

curl https://api.signals.pressone.africa/v1/webhooks/:endpoint_id/deliveries \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "attempt": 0,
      "attempted_at": "2024-08-25T15:00:00Z",
      "call_sequence": 0,
      "duration_ms": 0,
      "endpoint_id": "endpoint_id",
      "endpoint_url": "https://www.example.com/path/to/resource",
      "error": "error",
      "event_id": "event_id",
      "event_type": "event_type",
      "id": "id",
      "max_attempts": 0,
      "next_retry_at": "2024-08-25T15:00:00Z",
      "replay_request_id": "replay_request_id",
      "replay_requested_by": "replay_requested_by",
      "replayable_until": "2024-08-25T15:00:00Z",
      "resource": {
        "id": "id",
        "label": "label",
        "type": "type"
      },
      "result": "delivered",
      "status_code": 0
    }
  ]
}

json

application/json

Preview or queue webhook event replays

POST

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}/replays

Preview or queue webhook event replays › path Parameters

endpoint_id

string · required

Webhook endpoint id

Preview or queue webhook event replays › Headers

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Idempotency-Key

string

Required unless preview is true: one nonblank key of at most 128 characters.

Preview or queue webhook event replays › Request Body

ReplayWebhookEventsRequest

delivery_ids

string[] · required

event_types

string[] · required

preview

boolean · required

window_from

string · date-time · required

window_to

string · date-time · required

Preview or queue webhook event replays › Responses

A preview (preview true): the count for the selection. Nothing was queued.

WebhookReplayPreview

events

integer · int64 · min: 0 · required

rate_per_second

integer · int32 · min: 0 · required

window_from

string · date-time · required

window_to

string · date-time · required

POST/webhooks/{endpoint_id}/replays

curl https://api.signals.pressone.africa/v1/webhooks/:endpoint_id/replays \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "delivery_ids": [
    "string"
  ],
  "event_types": [
    "string"
  ],
  "preview": true,
  "window_from": "2024-08-25T15:00:00Z",
  "window_to": "2024-08-25T15:00:00Z"
}'

Example Request Body

{
  "delivery_ids": [
    "string"
  ],
  "event_types": [
    "string"
  ],
  "preview": true,
  "window_from": "2024-08-25T15:00:00Z",
  "window_to": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "events": 0,
  "rate_per_second": 0,
  "window_from": "2024-08-25T15:00:00Z",
  "window_to": "2024-08-25T15:00:00Z"
}

json

application/json

Send a signed webhook test event

POST

https://api.signals.pressone.africa/v1

/webhooks/{endpoint_id}/test

Send a signed webhook test event › path Parameters

endpoint_id

string · required

Webhook endpoint id

Send a signed webhook test event › Headers

Idempotency-Key

string · required

One nonblank key of at most 128 characters; a retry with the same key repeats the outcome.

X-Project-ID

string

The project the request acts on, as prj_ and its lowercase UUID; optional while the organization has one active project.

Send a signed webhook test event › Responses

The test delivery result. A target the endpoint owner controls answers 200 with the failing check.

WebhookTestResult

WebhookTestCheck[] · required

delivery_id

string · required

event_id

string · required

request_body

string · required

status_code

integer | null · int32 · min: 0 · required