Webhooks & Automation

Webhooks keep your tooling in sync without polling. NidFul webhooks surface real-time events tailored to African disclosure programs and integrate smoothly with regional infrastructures.

Enabling Webhooks

1. Navigate to Admin → Integrations → Webhooks.
2. Click Create endpoint and provide:
   • Target URL (HTTPS required)
   • Secret token for signature verification
   • Events to subscribe to
3. Test delivery with a sample payload.

Signature Verification

Each webhook request includes an X-NidFul-Signature header containing an HMAC SHA-256 signature.

import crypto from 'crypto';

function verifySignature(secret: string, payload: string, signature: string) {
  const digest = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

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

Reject requests when the signature does not match.

Available Events

• submission.created
• submission.state_changed
• submission.comment.created
• bounty.approved
• policy.updated
• program.invitation.sent

Payload Example

{
  "event": "submission.state_changed",
  "delivered_at": "2025-10-12T09:12:44Z",
  "data": {
    "id": "sub_98231",
    "title": "IDOR in airtime transfer API",
    "previous_state": "triaged",
    "current_state": "resolved",
    "severity": "high",
    "program": {
      "id": "prog_123",
      "name": "ExamplePay Bug Bounty"
    }
  }
}

Retry Logic

• NidFul retries failed deliveries up to 10 times with exponential backoff.
• Use idempotency keys in the X-NidFul-Delivery header to detect duplicates.
• Monitor webhook health in the dashboard and pause failing endpoints.

Regional Considerations

• Host endpoints in regions close to your primary operations (Nigeria, Kenya, South Africa, EU) to reduce latency.
• Ensure endpoints comply with local data residency laws if you forward payloads to third-party services.

Testing Tips

• Use the NidFul CLI or dashboard to replay historical events.
• Maintain separate sandbox endpoints for development and staging.
• Log signatures and payload hashes for audit purposes.

Combine webhooks with Core REST Endpoints to create robust, real-time workflows.