Webhook endpoints

List webhook endpoints

Lists the API client's webhook endpoints. signing_secret is never included.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

`application/json`

curl -X GET "https://example.com/v1/webhook_endpoints"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "url": "http://example.com",      "description": "string",      "events": [        "file.ready"      ],      "status": "active",      "created_at": "2019-08-24T14:15:22Z",      "signing_secret": "string"    }  ],  "next_cursor": "string"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Registers a webhook endpoint. The response is the only place the endpoint's signing_secret is ever returned — store it immediately; subsequent reads omit it. URLs must use https:// (plain http:// is allowed only for loopback addresses, for local development). Each API client may have at most 20 active endpoints.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Request Body

application/json

Delivery URL and optional event filters for the endpoint.

TypeScript Definitions

Use the request body type in TypeScript.

Delivery configuration used to register a webhook endpoint.

url*string

Delivery URL. Must use https://; plain http:// is allowed only for loopback addresses (127.0.0.1, ::1, localhost) to support local development receivers.

Formaturi

Lengthlength <= 2048

description?|

Free-text label shown in listings.

events?array<>|

Event type allow-list. Omitted or null subscribes the endpoint to all current and future event types.

Response Body

`application/json`

curl -X POST "https://example.com/v1/webhook_endpoints" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example-partner.com/aircredit/webhooks",    "description": "Production receiver",    "events": [      "file.ready",      "file.failed"    ]  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com",  "description": "string",  "events": [    "file.ready"  ],  "status": "active",  "created_at": "2019-08-24T14:15:22Z",  "signing_secret": "string"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Get a webhook endpoint

Returns one webhook endpoint. signing_secret is never included.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

endpoint_id*string

The webhook endpoint's id (WebhookEndpoint.id).

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/v1/webhook_endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com",  "description": "string",  "events": [    "file.ready"  ],  "status": "active",  "created_at": "2019-08-24T14:15:22Z",  "signing_secret": "string"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Update a webhook endpoint

Updates the endpoint's delivery configuration. Omitted fields stay unchanged. Setting status to disabled pauses deliveries (events emitted while disabled are not delivered later); setting it back to active resumes. Changing the URL does not change the signing secret.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

endpoint_id*string

The webhook endpoint's id (WebhookEndpoint.id).

Formatuuid

Request Body

application/json

The delivery configuration fields to change.

TypeScript Definitions

Use the request body type in TypeScript.

Webhook endpoint fields to change; omitted fields stay unchanged.

url?string

New delivery URL, subject to the same rules as at creation.

Formaturi

Lengthlength <= 2048

description?|

New free-text label, or null to clear it.

events?array<>|

New event type allow-list, or null to subscribe to all current and future types.

status?WebhookEndpointStatus

Set disabled to pause deliveries, active to resume.

Value in

"active"
"disabled"

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/webhook_endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com",  "description": "string",  "events": [    "file.ready"  ],  "status": "active",  "created_at": "2019-08-24T14:15:22Z",  "signing_secret": "string"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Delete a webhook endpoint

Deactivates and removes the endpoint from all listings. Event delivery history referencing the endpoint remains readable via the events API. Deleting an already-deleted endpoint returns 404.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

endpoint_id*string

The webhook endpoint's id (WebhookEndpoint.id).

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/webhook_endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

Rotate an endpoint's signing secret

Generates a new signing secret for the endpoint. The response is the only place the new secret is ever returned. During the 24-hour grace window, deliveries carry signatures for both secrets as multiple v1= values in X-Airtype-Signature — a verifier that accepts any matching v1= value keeps working throughout the rotation. After previous_secret_expires_at, the old secret stops signing. Rotating again within the grace window expires the previous secret immediately.

Authorization

bearerAuth

AuthorizationBearer <token>

Partner API key, sent as Authorization: Bearer <api key>.

In: header

Path Parameters

endpoint_id*string

The webhook endpoint's id (WebhookEndpoint.id).

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/v1/webhook_endpoints/497f6eca-6276-4993-bfeb-53cbbbba6f08/secret/rotations"

{  "signing_secret": "string",  "previous_secret_expires_at": "2019-08-24T14:15:22Z"}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

{  "error": {    "code": "invalid_field",    "message": "external_submission_id must not be empty",    "param": "external_submission_id",    "request_id": "req_9b2cf1f4-6f6e-4a7e-8f8e-2d5c7a1b0c3d"  }}

200application/json

401application/json

403application/json

429application/json

defaultapplication/json

201application/json

400application/json

401application/json

403application/json

409application/json

422application/json

429application/json

defaultapplication/json

200application/json

401application/json

403application/json

404application/json

429application/json

defaultapplication/json

200application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

defaultapplication/json

204

401application/json

403application/json

404application/json

429application/json

defaultapplication/json

201application/json

401application/json

403application/json

404application/json

429application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`