Webhooks

Piora Webhooks let you receive instant HTTP notifications when specific events occur. Use webhooks to integrate Slack notifications, trigger downstream processes, or build custom automation workflows.

Setting Up Webhooks

Create a Webhook

Go to “Settings” > “Webhooks”
Click “Add Webhook”
Configure the following parameters:

Parameter	Description	Example
URL	Endpoint to receive notifications	`https://your-server.com/webhook`
Events	Event types to listen for	Select one or more
Secret	Signing key (for verification)	Auto-generated or custom
Status	Enabled or disabled	Enabled

Event Types

Deployment Events

Event	Description
`deployment.started`	Deployment started
`deployment.succeeded`	Deployment succeeded
`deployment.failed`	Deployment failed
`deployment.rolled_back`	Deployment rolled back

Application Events

Event	Description
`application.created`	Application created
`application.deleted`	Application deleted
`application.started`	Application started
`application.stopped`	Application stopped
`application.crashed`	Application crashed unexpectedly

Server Events

Event	Description
`server.connected`	Server connected successfully
`server.disconnected`	Server connection lost
`server.alert`	Server alert (CPU, memory, etc.)

Database Events

Event	Description
`database.created`	Database created
`database.deleted`	Database deleted
`backup.completed`	Backup completed
`backup.failed`	Backup failed

Webhook Payload Format

Each webhook request is a POST with a JSON payload:

{
  "event": "deployment.succeeded",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "application": {
      "id": "app_xxxxxxxxxxxx",
      "name": "my-web-app"
    },
    "deployment": {
      "id": "deploy_xxxxxxxxxxxx",
      "status": "succeeded",
      "commit": "abc1234",
      "branch": "main",
      "duration": 45
    },
    "server": {
      "id": "srv_xxxxxxxxxxxx",
      "name": "production"
    }
  }
}

Signature Verification

Each webhook request includes a signature header to verify it genuinely came from Piora:

X-Piora-Signature: sha256=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Verification Example

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-piora-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Handle event...
  res.status(200).send('OK');
});

Retry Mechanism

If your webhook endpoint returns a non-2xx status code, Piora automatically retries:

Retry	Wait Time
1st	After 1 minute
2nd	After 5 minutes
3rd	After 30 minutes
4th	After 2 hours
5th	After 12 hours

After 5 retries, the event is marked as failed.

Webhook Logs

The dashboard shows the delivery history for each webhook:

Delivery time
Event type
HTTP status code
Response time
Payload content
Retry history