Selki Webhooks

Selki Developer Portal: Using API Docs & Webhooks

Selki provides powerful webhooks so you can be notified the instant an event happens or an alert is created. But what is a webhook??

Imagine a doorbell on your house.

When someone pushes it, you get notified — instantly.
You didn’t need to keep checking the door yourself every 2 miniutes. The doorbell told you!

Webhooks work the same way:

When something happens in Selki (like a phishing email is clicked), your system gets notified in real-time.

How to Set Up a Webhook in Selki

Selki makes webhook creation super easy with a guided wizard. Here's how:

Create New Webhook

Fields to complete:

Webhook Name: A friendly name (e.g., “Notify Slack on Clicks”)
Endpoint URL: Where Selki should send event data (your server)

Choose your events:

Email Sent: When Selki successfully sends a phishing test
Email Opened: A recipient opened the test
Email Clicked: A recipient clicked a phishing link
Email Reported: A recipient flagged the email as suspicious
Email Error: Something went wrong
New Threat: A real security threat was detected in Selki

Advanced Settings

Extra settings for reliability and security:

Signing Secret: Optional. If added, Selki signs each request with HMAC SHA256 to verify it's really us.
Retry Attempts: If your server is down, how many times should we retry?
Retry Delay: How long to wait between tries.
Custom Headers: Add anything your server needs (e.g., an Authorization token).

Webhook Overview

Once created, your webhook dashboard shows:

Webhook URL
Subscribed Events
Security Settings
Headers being sent
Success Rate & Call Stats

This is your real-time health check of the integration.

Webhook Recent Calls

Every time an event happens, we log the webhook call:

Status: Success or failed
HTTP Code: 200 means success, 404 means your endpoint didn’t exist
Response Time: How quickly your server replied
Event Type: What triggered it (e.g., Email Clicked)

You can debug failed deliveries here.

Webhook Documentation

Learn exactly what Selki sends in each webhook call:

Headers:
- Selki-Webhook-ID: Unique per webhook
- Selki-Webhook-Call-ID: Unique per call
- Selki-Signature: If you use a secret
Body Format:

json
CopyEdit{
  "timestamp": "2025-08-07T10:01:42Z",
  "subscription": "PHISHING_EMAIL_CLICKED",
  "data": {
    "campaignId": "abc123",
    "email": "user@example.com"
  }
}

Payload Structures

The payload will vary depending on the event type:

Example 1: `THREATS_NEW_THREAT`

json
CopyEdit{
  "id": "threat123",
  "category": "EMPLOYEES",
  "riskLevel": "CRITICAL",
  "url": "http://leakeddomain.com",
  "username": "jdoe",
  "email": "jdoe@company.com"
}

Example 2: `PHISHING_EMAIL_CLICKED`

json
CopyEdit{
  "campaignId": "phish123",
  "email": "staff@company.com"
}

Each webhook follows strict typing so you can integrate reliably.

Webhook Settings & Danger Zone

Update settings anytime:

Enable/disable events
Change retry and secret settings
🔴 Delete Webhook — irreversible! Use with caution.

Final Tips

Test your webhook using a tool like [webhook.site]()
Monitor failed calls under “Recent Calls”
Keep your endpoint up and responsive — we retry, but not forever

You're Ready!

Now that you understand Selki's API and Webhooks:

Use the GraphQL API to fetch tailored threat insights.
Use Webhooks to get real-time alerts into your workflows (Slack, PagerDuty, SIEMs, etc.)

Need more help? Contact support@selki.io

Updated on: 08/08/2025

Was this article helpful?

Thank you!