Scheduler API Documentation

Overview

The Scheduler API allows you to schedule JSON messages to be sent to specified endpoints at specific times. The API supports two versions:

V1 API: Simple API for sending one-time messages to specified URLs
V2 API: More sophisticated API for managing endpoints, messages, and security mechanisms

Authentication

All API endpoints require authentication using Laravel Sanctum. You must include a valid authentication token in your requests.

API Endpoints

V1 API

Send a Message

POST /api/v1/messages

Schedule a JSON message to be sent to a specified URL.

Request Body:

Parameter	Type	Required	Description
endpoint	string	Yes	The URL where the message will be sent
message	JSON	Yes	The JSON message to be sent
available_at	string	No	When to send the message (format: Y-m-d H:i:s). If not provided, the message will be sent immediately

Example Request:

{
    "endpoint": "https://example.com/webhook",
    "message": {
        "key": "value",
        "another_key": "another_value"
    },
    "available_at": "2023-12-31 23:59:59"
}

Response:

{
    "message": "Mensagem enfileirada com sucesso"
}

V2 API

Endpoints

List All Endpoints

GET /api/v2/endpoints

Get a list of all endpoints for the authenticated user.

Response:

{
    "message": "Endpoints listados com sucesso",
    "resources": [
        {
            "id": 1,
            "url": "https://example.com/webhook",
            "user_id": 1,
            "created_at": "2023-01-01T00:00:00.000000Z",
            "updated_at": "2023-01-01T00:00:00.000000Z"
        }
    ]
}

Create an Endpoint

POST /api/v2/endpoints

Create a new endpoint.

Request Body:

Parameter	Type	Required	Description
url	string	Yes	The URL of the endpoint

Example Request:

{
    "url": "https://example.com/webhook"
}

Response:

{
    "message": "Endpoint criado com sucesso",
    "resource": {
        "id": 1,
        "url": "https://example.com/webhook",
        "user_id": 1,
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Get an Endpoint

GET /api/v2/endpoints/{endpoint_id}

Get details of a specific endpoint, including its messages and security settings.

Response:

{
    "message": "Endpoint encontrado",
    "resource": {
        "id": 1,
        "url": "https://example.com/webhook",
        "user_id": 1,
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z",
        "messages": [],
        "securities": []
    }
}

Update an Endpoint

PUT /api/v2/endpoints/{endpoint_id}

Update an existing endpoint.

Request Body:

Parameter	Type	Required	Description
url	string	Yes	The new URL of the endpoint

Example Request:

{
    "url": "https://example.com/new-webhook"
}

Response:

{
    "message": "Endpoint atualizado com sucesso"
}

Delete an Endpoint

DELETE /api/v2/endpoints/{endpoint_id}

Delete an endpoint. This will only work if the endpoint has no unsent messages.

Response:

{
    "message": "Endpoint removido com sucesso"
}

Messages

List Messages for an Endpoint

GET /api/v2/endpoints/{endpoint_id}/messages

Get a list of all messages for a specific endpoint.

Response:

{
    "message": "Messages listadas com sucesso",
    "resources": [
        {
            "id": 1,
            "content": "{\"key\":\"value\"}",
            "endpoint_id": 1,
            "is_sent": false,
            "created_at": "2023-01-01T00:00:00.000000Z",
            "updated_at": "2023-01-01T00:00:00.000000Z"
        }
    ]
}

Create a Message for an Endpoint

POST /api/v2/endpoints/{endpoint_id}/messages

Create a new message for a specific endpoint.

Request Body:

Parameter	Type	Required	Description
content	JSON	Yes	The JSON content of the message
send_at	string	No	When to send the message (format: Y-m-d H:i:s). If not provided, the message will be sent immediately

Example Request:

{
    "content": {
        "key": "value",
        "another_key": "another_value"
    },
    "send_at": "2023-12-31 23:59:59"
}

Response:

{
    "message": "Message criada com sucesso",
    "resource": {
        "id": 1,
        "content": "{\"key\":\"value\",\"another_key\":\"another_value\"}",
        "endpoint_id": 1,
        "is_sent": false,
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Get a Message

GET /api/v2/messages/{message_id}

Get details of a specific message.

Response:

{
    "message": "Message encontrada",
    "resource": {
        "id": 1,
        "content": "{\"key\":\"value\",\"another_key\":\"another_value\"}",
        "endpoint_id": 1,
        "is_sent": false,
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z",
        "endpoint": {
            "id": 1,
            "url": "https://example.com/webhook",
            "user_id": 1,
            "created_at": "2023-01-01T00:00:00.000000Z",
            "updated_at": "2023-01-01T00:00:00.000000Z"
        }
    }
}

Update a Message

PUT /api/v2/messages/{message_id}

Update an existing message.

Request Body:

Parameter	Type	Required	Description
content	JSON	Yes	The new JSON content of the message

Example Request:

{
    "content": {
        "key": "new_value",
        "another_key": "new_another_value"
    }
}

Response:

{
    "message": "Message atualizada com sucesso"
}

Delete a Message

DELETE /api/v2/messages/{message_id}

Delete a message. This will only work if the message has already been sent.

Response:

{
    "message": "Message removida com sucesso"
}

HMAC Authentication

Add HMAC Authentication to an Endpoint

POST /api/v2/endpoints/{endpoint_id}/hmacs

Add HMAC authentication to a specific endpoint.

Request Body:

Parameter	Type	Required	Description
header	string	Yes	The name of the header to use for HMAC
secret_key	string	Yes	The secret key to use for HMAC calculation

Example Request:

{
    "header": "X-HMAC-Signature",
    "secret_key": "your-secret-key"
}

Response:

{
    "message": "Hmac criada com sucesso",
    "resource": {
        "id": 1,
        "header": "X-HMAC-Signature",
        "secret_key": "your-secret-key",
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Get HMAC Authentication

GET /api/v2/hmacs/{hmac_id}

Get details of a specific HMAC authentication.

Response:

{
    "message": "Hmac encontrada",
    "resource": {
        "id": 1,
        "header": "X-HMAC-Signature",
        "secret_key": "your-secret-key",
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Delete HMAC Authentication

DELETE /api/v2/hmacs/{hmac_id}

Remove HMAC authentication from an endpoint.

Response:

{
    "message": "Hmac removida com sucesso"
}

Authorization Headers

Add Authorization Header to an Endpoint

POST /api/v2/endpoints/{endpoint_id}/authorization-headers

Add an authorization header to a specific endpoint.

Request Body:

Parameter	Type	Required	Description
key	string	Yes	The name of the header
value	string	Yes	The value of the header

Example Request:

{
    "key": "Authorization",
    "value": "Bearer your-token"
}

Response:

{
    "message": "AuthorizationHeader criada com sucesso",
    "resource": {
        "id": 1,
        "key": "Authorization",
        "value": "Bearer your-token",
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Get Authorization Header

GET /api/v2/authorization-headers/{authorization_header_id}

Get details of a specific authorization header.

Response:

{
    "message": "AuthorizationHeader encontrada",
    "resource": {
        "id": 1,
        "key": "Authorization",
        "value": "Bearer your-token",
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-01T00:00:00.000000Z"
    }
}

Delete Authorization Header

DELETE /api/v2/authorization-headers/{authorization_header_id}

Remove an authorization header from an endpoint.

Response:

{
    "message": "AuthorizationHeader removida com sucesso"
}

Error Handling

The API returns appropriate HTTP status codes and error messages for different types of errors:

400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication failed
403 Forbidden: Permission denied
404 Not Found: Resource not found
422 Unprocessable Entity: Validation failed or operation not allowed
500 Internal Server Error: Server error

Example error response:

{
    "message": "The given data was invalid.",
    "errors": {
        "endpoint": [
            "The endpoint field is required."
        ]
    }
}